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 CX_EXPORT CxJsonWriter cxJsonWriterCompact(void); |
479 CxJsonWriter cxJsonWriterCompact(void); |
|
480 |
479 |
481 /** |
480 /** |
482 * Creates a default writer configuration for pretty output. |
481 * Creates a default writer configuration for pretty output. |
483 * |
482 * |
484 * @param use_spaces false if you want tabs, true if you want four spaces instead |
483 * @param use_spaces false if you want tabs, true if you want four spaces instead |
485 * @return new JSON writer settings |
484 * @return new JSON writer settings |
486 */ |
485 */ |
487 cx_attr_nodiscard |
486 cx_attr_nodiscard |
488 cx_attr_export |
487 CX_EXPORT CxJsonWriter cxJsonWriterPretty(bool use_spaces); |
489 CxJsonWriter cxJsonWriterPretty(bool use_spaces); |
|
490 |
488 |
491 /** |
489 /** |
492 * Writes a JSON value to a buffer or stream. |
490 * Writes a JSON value to a buffer or stream. |
493 * |
491 * |
494 * This function blocks until either all data is written, or an error occurs. |
492 * This function blocks until either all data is written, or an error occurs. |
505 * @param settings formatting settings (or @c NULL to use a compact default) |
503 * @param settings formatting settings (or @c NULL to use a compact default) |
506 * @retval zero success |
504 * @retval zero success |
507 * @retval non-zero when no or not all data could be written |
505 * @retval non-zero when no or not all data could be written |
508 */ |
506 */ |
509 cx_attr_nonnull_arg(1, 2, 3) |
507 cx_attr_nonnull_arg(1, 2, 3) |
510 cx_attr_export |
508 CX_EXPORT int cxJsonWrite(void* target, const CxJsonValue* value, |
511 int cxJsonWrite( |
509 cx_write_func wfunc, const CxJsonWriter* settings); |
512 void* target, |
|
513 const CxJsonValue* value, |
|
514 cx_write_func wfunc, |
|
515 const CxJsonWriter* settings |
|
516 ); |
|
517 |
510 |
518 /** |
511 /** |
519 * Initializes the JSON interface. |
512 * Initializes the JSON interface. |
520 * |
513 * |
521 * @param json the JSON interface |
514 * @param json the JSON interface |
522 * @param allocator the allocator that shall be used for the produced values |
515 * @param allocator the allocator that shall be used for the produced values |
523 * @see cxJsonDestroy() |
516 * @see cxJsonDestroy() |
524 */ |
517 */ |
525 cx_attr_nonnull_arg(1) |
518 cx_attr_nonnull_arg(1) |
526 cx_attr_export |
519 CX_EXPORT void cxJsonInit(CxJson *json, const CxAllocator *allocator); |
527 void cxJsonInit(CxJson *json, const CxAllocator *allocator); |
|
528 |
520 |
529 /** |
521 /** |
530 * Destroys the JSON interface. |
522 * Destroys the JSON interface. |
531 * |
523 * |
532 * @param json the JSON interface |
524 * @param json the JSON interface |
533 * @see cxJsonInit() |
525 * @see cxJsonInit() |
534 */ |
526 */ |
535 cx_attr_nonnull |
527 cx_attr_nonnull |
536 cx_attr_export |
528 CX_EXPORT void cxJsonDestroy(CxJson *json); |
537 void cxJsonDestroy(CxJson *json); |
|
538 |
529 |
539 /** |
530 /** |
540 * Destroys and re-initializes the JSON interface. |
531 * Destroys and re-initializes the JSON interface. |
541 * |
532 * |
542 * You might want to use this to reset the parser after |
533 * You might want to use this to reset the parser after |
543 * encountering a syntax error. |
534 * encountering a syntax error. |
544 * |
535 * |
545 * @param json the JSON interface |
536 * @param json the JSON interface |
546 */ |
537 */ |
547 cx_attr_nonnull |
538 cx_attr_nonnull |
548 static inline void cxJsonReset(CxJson *json) { |
539 CX_EXPORT void cxJsonReset(CxJson *json); |
549 const CxAllocator *allocator = json->allocator; |
|
550 cxJsonDestroy(json); |
|
551 cxJsonInit(json, allocator); |
|
552 } |
|
553 |
540 |
554 /** |
541 /** |
555 * Fills the input buffer. |
542 * Fills the input buffer. |
556 * |
543 * |
557 * @remark The JSON interface tries to avoid copying the input data. |
544 * @remark The JSON interface tries to avoid copying the input data. |
567 * @param len the length of the source buffer |
554 * @param len the length of the source buffer |
568 * @retval zero success |
555 * @retval zero success |
569 * @retval non-zero internal allocation error |
556 * @retval non-zero internal allocation error |
570 * @see cxJsonFill() |
557 * @see cxJsonFill() |
571 */ |
558 */ |
572 cx_attr_nonnull |
559 cx_attr_nonnull cx_attr_access_r(2, 3) |
573 cx_attr_access_r(2, 3) |
560 CX_EXPORT int cxJsonFilln(CxJson *json, const char *buf, size_t len); |
574 cx_attr_export |
|
575 int cxJsonFilln(CxJson *json, const char *buf, size_t len); |
|
576 |
561 |
577 |
562 |
578 /** |
563 /** |
579 * Internal function, do not use. |
564 * Internal function, do not use. |
580 * |
565 * |
582 * @param str the string |
567 * @param str the string |
583 * @retval zero success |
568 * @retval zero success |
584 * @retval non-zero internal allocation error |
569 * @retval non-zero internal allocation error |
585 */ |
570 */ |
586 cx_attr_nonnull |
571 cx_attr_nonnull |
587 static inline int cx_json_fill(CxJson *json, cxstring str) { |
572 CX_INLINE int cx_json_fill(CxJson *json, cxstring str) { |
588 return cxJsonFilln(json, str.ptr, str.length); |
573 return cxJsonFilln(json, str.ptr, str.length); |
589 } |
574 } |
590 |
575 |
591 /** |
576 /** |
592 * Fills the input buffer. |
577 * Fills the input buffer. |
614 * @return the new JSON object or @c NULL if allocation fails |
599 * @return the new JSON object or @c NULL if allocation fails |
615 * @see cxJsonObjPutObj() |
600 * @see cxJsonObjPutObj() |
616 * @see cxJsonArrAddValues() |
601 * @see cxJsonArrAddValues() |
617 */ |
602 */ |
618 cx_attr_nodiscard |
603 cx_attr_nodiscard |
619 cx_attr_export |
604 CX_EXPORT CxJsonValue* cxJsonCreateObj(const CxAllocator* allocator); |
620 CxJsonValue* cxJsonCreateObj(const CxAllocator* allocator); |
|
621 |
605 |
622 /** |
606 /** |
623 * Creates a new (empty) JSON array. |
607 * Creates a new (empty) JSON array. |
624 * |
608 * |
625 * @param allocator the allocator to use |
609 * @param allocator the allocator to use |
626 * @return the new JSON array or @c NULL if allocation fails |
610 * @return the new JSON array or @c NULL if allocation fails |
627 * @see cxJsonObjPutArr() |
611 * @see cxJsonObjPutArr() |
628 * @see cxJsonArrAddValues() |
612 * @see cxJsonArrAddValues() |
629 */ |
613 */ |
630 cx_attr_nodiscard |
614 cx_attr_nodiscard |
631 cx_attr_export |
615 CX_EXPORT CxJsonValue* cxJsonCreateArr(const CxAllocator* allocator); |
632 CxJsonValue* cxJsonCreateArr(const CxAllocator* allocator); |
|
633 |
616 |
634 /** |
617 /** |
635 * Creates a new JSON number value. |
618 * Creates a new JSON number value. |
636 * |
619 * |
637 * @param allocator the allocator to use |
620 * @param allocator the allocator to use |
639 * @return the new JSON value or @c NULL if allocation fails |
622 * @return the new JSON value or @c NULL if allocation fails |
640 * @see cxJsonObjPutNumber() |
623 * @see cxJsonObjPutNumber() |
641 * @see cxJsonArrAddNumbers() |
624 * @see cxJsonArrAddNumbers() |
642 */ |
625 */ |
643 cx_attr_nodiscard |
626 cx_attr_nodiscard |
644 cx_attr_export |
627 CX_EXPORT CxJsonValue* cxJsonCreateNumber(const CxAllocator* allocator, double num); |
645 CxJsonValue* cxJsonCreateNumber(const CxAllocator* allocator, double num); |
|
646 |
628 |
647 /** |
629 /** |
648 * Creates a new JSON number value based on an integer. |
630 * Creates a new JSON number value based on an integer. |
649 * |
631 * |
650 * @param allocator the allocator to use |
632 * @param allocator the allocator to use |
652 * @return the new JSON value or @c NULL if allocation fails |
634 * @return the new JSON value or @c NULL if allocation fails |
653 * @see cxJsonObjPutInteger() |
635 * @see cxJsonObjPutInteger() |
654 * @see cxJsonArrAddIntegers() |
636 * @see cxJsonArrAddIntegers() |
655 */ |
637 */ |
656 cx_attr_nodiscard |
638 cx_attr_nodiscard |
657 cx_attr_export |
639 CX_EXPORT CxJsonValue* cxJsonCreateInteger(const CxAllocator* allocator, int64_t num); |
658 CxJsonValue* cxJsonCreateInteger(const CxAllocator* allocator, int64_t num); |
|
659 |
640 |
660 /** |
641 /** |
661 * Creates a new JSON string. |
642 * Creates a new JSON string. |
662 * |
643 * |
663 * @param allocator the allocator to use |
644 * @param allocator the allocator to use |
665 * @return the new JSON value or @c NULL if allocation fails |
646 * @return the new JSON value or @c NULL if allocation fails |
666 * @see cxJsonCreateString() |
647 * @see cxJsonCreateString() |
667 * @see cxJsonObjPutString() |
648 * @see cxJsonObjPutString() |
668 * @see cxJsonArrAddStrings() |
649 * @see cxJsonArrAddStrings() |
669 */ |
650 */ |
670 cx_attr_nodiscard |
651 cx_attr_nodiscard cx_attr_nonnull_arg(2) cx_attr_cstr_arg(2) |
671 cx_attr_nonnull_arg(2) |
652 CX_EXPORT CxJsonValue* cxJsonCreateString(const CxAllocator* allocator, const char *str); |
672 cx_attr_cstr_arg(2) |
|
673 cx_attr_export |
|
674 CxJsonValue* cxJsonCreateString(const CxAllocator* allocator, const char *str); |
|
675 |
653 |
676 /** |
654 /** |
677 * Creates a new JSON string. |
655 * Creates a new JSON string. |
678 * |
656 * |
679 * @param allocator the allocator to use |
657 * @param allocator the allocator to use |
682 * @see cxJsonCreateCxString() |
660 * @see cxJsonCreateCxString() |
683 * @see cxJsonObjPutCxString() |
661 * @see cxJsonObjPutCxString() |
684 * @see cxJsonArrAddCxStrings() |
662 * @see cxJsonArrAddCxStrings() |
685 */ |
663 */ |
686 cx_attr_nodiscard |
664 cx_attr_nodiscard |
687 cx_attr_export |
665 CX_EXPORT CxJsonValue* cxJsonCreateCxString(const CxAllocator* allocator, cxstring str); |
688 CxJsonValue* cxJsonCreateCxString(const CxAllocator* allocator, cxstring str); |
|
689 |
666 |
690 /** |
667 /** |
691 * Creates a new JSON literal. |
668 * Creates a new JSON literal. |
692 * |
669 * |
693 * @param allocator the allocator to use |
670 * @param allocator the allocator to use |
695 * @return the new JSON value or @c NULL if allocation fails |
672 * @return the new JSON value or @c NULL if allocation fails |
696 * @see cxJsonObjPutLiteral() |
673 * @see cxJsonObjPutLiteral() |
697 * @see cxJsonArrAddLiterals() |
674 * @see cxJsonArrAddLiterals() |
698 */ |
675 */ |
699 cx_attr_nodiscard |
676 cx_attr_nodiscard |
700 cx_attr_export |
677 CX_EXPORT CxJsonValue* cxJsonCreateLiteral(const CxAllocator* allocator, CxJsonLiteral lit); |
701 CxJsonValue* cxJsonCreateLiteral(const CxAllocator* allocator, CxJsonLiteral lit); |
|
702 |
678 |
703 /** |
679 /** |
704 * Adds number values to a JSON array. |
680 * Adds number values to a JSON array. |
705 * |
681 * |
706 * @param arr the JSON array |
682 * @param arr the JSON array |
707 * @param num the array of values |
683 * @param num the array of values |
708 * @param count the number of elements |
684 * @param count the number of elements |
709 * @retval zero success |
685 * @retval zero success |
710 * @retval non-zero allocation failure |
686 * @retval non-zero allocation failure |
711 */ |
687 */ |
712 cx_attr_nonnull |
688 cx_attr_nonnull cx_attr_access_r(2, 3) |
713 cx_attr_access_r(2, 3) |
689 CX_EXPORT int cxJsonArrAddNumbers(CxJsonValue* arr, const double* num, size_t count); |
714 cx_attr_export |
|
715 int cxJsonArrAddNumbers(CxJsonValue* arr, const double* num, size_t count); |
|
716 |
690 |
717 /** |
691 /** |
718 * Adds number values, of which all are integers, to a JSON array. |
692 * Adds number values, of which all are integers, to a JSON array. |
719 * |
693 * |
720 * @param arr the JSON array |
694 * @param arr the JSON array |
721 * @param num the array of values |
695 * @param num the array of values |
722 * @param count the number of elements |
696 * @param count the number of elements |
723 * @retval zero success |
697 * @retval zero success |
724 * @retval non-zero allocation failure |
698 * @retval non-zero allocation failure |
725 */ |
699 */ |
726 cx_attr_nonnull |
700 cx_attr_nonnull cx_attr_access_r(2, 3) |
727 cx_attr_access_r(2, 3) |
701 CX_EXPORT int cxJsonArrAddIntegers(CxJsonValue* arr, const int64_t* num, size_t count); |
728 cx_attr_export |
|
729 int cxJsonArrAddIntegers(CxJsonValue* arr, const int64_t* num, size_t count); |
|
730 |
702 |
731 /** |
703 /** |
732 * Adds strings to a JSON array. |
704 * Adds strings to a JSON array. |
733 * |
705 * |
734 * The strings will be copied with the allocator of the array. |
706 * The strings will be copied with the allocator of the array. |
738 * @param count the number of elements |
710 * @param count the number of elements |
739 * @retval zero success |
711 * @retval zero success |
740 * @retval non-zero allocation failure |
712 * @retval non-zero allocation failure |
741 * @see cxJsonArrAddCxStrings() |
713 * @see cxJsonArrAddCxStrings() |
742 */ |
714 */ |
743 cx_attr_nonnull |
715 cx_attr_nonnull cx_attr_access_r(2, 3) |
744 cx_attr_access_r(2, 3) |
716 CX_EXPORT int cxJsonArrAddStrings(CxJsonValue* arr, const char* const* str, size_t count); |
745 cx_attr_export |
|
746 int cxJsonArrAddStrings(CxJsonValue* arr, const char* const* str, size_t count); |
|
747 |
717 |
748 /** |
718 /** |
749 * Adds strings to a JSON array. |
719 * Adds strings to a JSON array. |
750 * |
720 * |
751 * The strings will be copied with the allocator of the array. |
721 * The strings will be copied with the allocator of the array. |
755 * @param count the number of elements |
725 * @param count the number of elements |
756 * @retval zero success |
726 * @retval zero success |
757 * @retval non-zero allocation failure |
727 * @retval non-zero allocation failure |
758 * @see cxJsonArrAddStrings() |
728 * @see cxJsonArrAddStrings() |
759 */ |
729 */ |
760 cx_attr_nonnull |
730 cx_attr_nonnull cx_attr_access_r(2, 3) |
761 cx_attr_access_r(2, 3) |
731 CX_EXPORT int cxJsonArrAddCxStrings(CxJsonValue* arr, const cxstring* str, size_t count); |
762 cx_attr_export |
|
763 int cxJsonArrAddCxStrings(CxJsonValue* arr, const cxstring* str, size_t count); |
|
764 |
732 |
765 /** |
733 /** |
766 * Adds literals to a JSON array. |
734 * Adds literals to a JSON array. |
767 * |
735 * |
768 * @param arr the JSON array |
736 * @param arr the JSON array |
769 * @param lit the array of literal types |
737 * @param lit the array of literal types |
770 * @param count the number of elements |
738 * @param count the number of elements |
771 * @retval zero success |
739 * @retval zero success |
772 * @retval non-zero allocation failure |
740 * @retval non-zero allocation failure |
773 */ |
741 */ |
774 cx_attr_nonnull |
742 cx_attr_nonnull cx_attr_access_r(2, 3) |
775 cx_attr_access_r(2, 3) |
743 CX_EXPORT int cxJsonArrAddLiterals(CxJsonValue* arr, const CxJsonLiteral* lit, size_t count); |
776 cx_attr_export |
|
777 int cxJsonArrAddLiterals(CxJsonValue* arr, const CxJsonLiteral* lit, size_t count); |
|
778 |
744 |
779 /** |
745 /** |
780 * Add arbitrary values to a JSON array. |
746 * Add arbitrary values to a JSON array. |
781 * |
747 * |
782 * @attention In contrast to all other add functions, this function adds the values |
748 * @attention In contrast to all other add functions, this function adds the values |
786 * @param val the values |
752 * @param val the values |
787 * @param count the number of elements |
753 * @param count the number of elements |
788 * @retval zero success |
754 * @retval zero success |
789 * @retval non-zero allocation failure |
755 * @retval non-zero allocation failure |
790 */ |
756 */ |
791 cx_attr_nonnull |
757 cx_attr_nonnull cx_attr_access_r(2, 3) |
792 cx_attr_access_r(2, 3) |
758 CX_EXPORT int cxJsonArrAddValues(CxJsonValue* arr, CxJsonValue* const* val, size_t count); |
793 cx_attr_export |
|
794 int cxJsonArrAddValues(CxJsonValue* arr, CxJsonValue* const* val, size_t count); |
|
795 |
759 |
796 /** |
760 /** |
797 * Adds or replaces a value within a JSON object. |
761 * Adds or replaces a value within a JSON object. |
798 * |
762 * |
799 * The value will be directly added and not copied. |
763 * The value will be directly added and not copied. |
806 * @param child the value |
770 * @param child the value |
807 * @retval zero success |
771 * @retval zero success |
808 * @retval non-zero allocation failure |
772 * @retval non-zero allocation failure |
809 */ |
773 */ |
810 cx_attr_nonnull |
774 cx_attr_nonnull |
811 cx_attr_export |
775 CX_EXPORT int cxJsonObjPut(CxJsonValue* obj, cxstring name, CxJsonValue* child); |
812 int cxJsonObjPut(CxJsonValue* obj, cxstring name, CxJsonValue* child); |
|
813 |
776 |
814 /** |
777 /** |
815 * Creates a new JSON object and adds it to an existing object. |
778 * Creates a new JSON object and adds it to an existing object. |
816 * |
779 * |
817 * @param obj the target JSON object |
780 * @param obj the target JSON object |
819 * @return the new value or @c NULL if allocation fails |
782 * @return the new value or @c NULL if allocation fails |
820 * @see cxJsonObjPut() |
783 * @see cxJsonObjPut() |
821 * @see cxJsonCreateObj() |
784 * @see cxJsonCreateObj() |
822 */ |
785 */ |
823 cx_attr_nonnull |
786 cx_attr_nonnull |
824 cx_attr_export |
787 CX_EXPORT CxJsonValue* cxJsonObjPutObj(CxJsonValue* obj, cxstring name); |
825 CxJsonValue* cxJsonObjPutObj(CxJsonValue* obj, cxstring name); |
|
826 |
788 |
827 /** |
789 /** |
828 * Creates a new JSON array and adds it to an object. |
790 * Creates a new JSON array and adds it to an object. |
829 * |
791 * |
830 * @param obj the target JSON object |
792 * @param obj the target JSON object |
832 * @return the new value or @c NULL if allocation fails |
794 * @return the new value or @c NULL if allocation fails |
833 * @see cxJsonObjPut() |
795 * @see cxJsonObjPut() |
834 * @see cxJsonCreateArr() |
796 * @see cxJsonCreateArr() |
835 */ |
797 */ |
836 cx_attr_nonnull |
798 cx_attr_nonnull |
837 cx_attr_export |
799 CX_EXPORT CxJsonValue* cxJsonObjPutArr(CxJsonValue* obj, cxstring name); |
838 CxJsonValue* cxJsonObjPutArr(CxJsonValue* obj, cxstring name); |
|
839 |
800 |
840 /** |
801 /** |
841 * Creates a new JSON number and adds it to an object. |
802 * Creates a new JSON number and adds it to an object. |
842 * |
803 * |
843 * @param obj the target JSON object |
804 * @param obj the target JSON object |
846 * @return the new value or @c NULL if allocation fails |
807 * @return the new value or @c NULL if allocation fails |
847 * @see cxJsonObjPut() |
808 * @see cxJsonObjPut() |
848 * @see cxJsonCreateNumber() |
809 * @see cxJsonCreateNumber() |
849 */ |
810 */ |
850 cx_attr_nonnull |
811 cx_attr_nonnull |
851 cx_attr_export |
812 CX_EXPORT CxJsonValue* cxJsonObjPutNumber(CxJsonValue* obj, cxstring name, double num); |
852 CxJsonValue* cxJsonObjPutNumber(CxJsonValue* obj, cxstring name, double num); |
|
853 |
813 |
854 /** |
814 /** |
855 * Creates a new JSON number, based on an integer, and adds it to an object. |
815 * Creates a new JSON number, based on an integer, and adds it to an object. |
856 * |
816 * |
857 * @param obj the target JSON object |
817 * @param obj the target JSON object |
860 * @return the new value or @c NULL if allocation fails |
820 * @return the new value or @c NULL if allocation fails |
861 * @see cxJsonObjPut() |
821 * @see cxJsonObjPut() |
862 * @see cxJsonCreateInteger() |
822 * @see cxJsonCreateInteger() |
863 */ |
823 */ |
864 cx_attr_nonnull |
824 cx_attr_nonnull |
865 cx_attr_export |
825 CX_EXPORT CxJsonValue* cxJsonObjPutInteger(CxJsonValue* obj, cxstring name, int64_t num); |
866 CxJsonValue* cxJsonObjPutInteger(CxJsonValue* obj, cxstring name, int64_t num); |
|
867 |
826 |
868 /** |
827 /** |
869 * Creates a new JSON string and adds it to an object. |
828 * Creates a new JSON string and adds it to an object. |
870 * |
829 * |
871 * The string data is copied. |
830 * The string data is copied. |
875 * @param str the string data |
834 * @param str the string data |
876 * @return the new value or @c NULL if allocation fails |
835 * @return the new value or @c NULL if allocation fails |
877 * @see cxJsonObjPut() |
836 * @see cxJsonObjPut() |
878 * @see cxJsonCreateString() |
837 * @see cxJsonCreateString() |
879 */ |
838 */ |
880 cx_attr_nonnull |
839 cx_attr_nonnull cx_attr_cstr_arg(3) |
881 cx_attr_cstr_arg(3) |
840 CX_EXPORT CxJsonValue* cxJsonObjPutString(CxJsonValue* obj, cxstring name, const char* str); |
882 cx_attr_export |
|
883 CxJsonValue* cxJsonObjPutString(CxJsonValue* obj, cxstring name, const char* str); |
|
884 |
841 |
885 /** |
842 /** |
886 * Creates a new JSON string and adds it to an object. |
843 * Creates a new JSON string and adds it to an object. |
887 * |
844 * |
888 * The string data is copied. |
845 * The string data is copied. |
893 * @return the new value or @c NULL if allocation fails |
850 * @return the new value or @c NULL if allocation fails |
894 * @see cxJsonObjPut() |
851 * @see cxJsonObjPut() |
895 * @see cxJsonCreateCxString() |
852 * @see cxJsonCreateCxString() |
896 */ |
853 */ |
897 cx_attr_nonnull |
854 cx_attr_nonnull |
898 cx_attr_export |
855 CX_EXPORT CxJsonValue* cxJsonObjPutCxString(CxJsonValue* obj, cxstring name, cxstring str); |
899 CxJsonValue* cxJsonObjPutCxString(CxJsonValue* obj, cxstring name, cxstring str); |
|
900 |
856 |
901 /** |
857 /** |
902 * Creates a new JSON literal and adds it to an object. |
858 * Creates a new JSON literal and adds it to an object. |
903 * |
859 * |
904 * @param obj the target JSON object |
860 * @param obj the target JSON object |
907 * @return the new value or @c NULL if allocation fails |
863 * @return the new value or @c NULL if allocation fails |
908 * @see cxJsonObjPut() |
864 * @see cxJsonObjPut() |
909 * @see cxJsonCreateLiteral() |
865 * @see cxJsonCreateLiteral() |
910 */ |
866 */ |
911 cx_attr_nonnull |
867 cx_attr_nonnull |
912 cx_attr_export |
868 CX_EXPORT CxJsonValue* cxJsonObjPutLiteral(CxJsonValue* obj, cxstring name, CxJsonLiteral lit); |
913 CxJsonValue* cxJsonObjPutLiteral(CxJsonValue* obj, cxstring name, CxJsonLiteral lit); |
|
914 |
869 |
915 /** |
870 /** |
916 * Recursively deallocates the memory of a JSON value. |
871 * Recursively deallocates the memory of a JSON value. |
917 * |
872 * |
918 * @remark The type of each deallocated value will be changed |
873 * @remark The type of each deallocated value will be changed |
921 * you from double-frees when you are accidentally freeing |
876 * you from double-frees when you are accidentally freeing |
922 * a nested value and then the parent value (or vice versa). |
877 * a nested value and then the parent value (or vice versa). |
923 * |
878 * |
924 * @param value the value |
879 * @param value the value |
925 */ |
880 */ |
926 cx_attr_export |
881 CX_EXPORT void cxJsonValueFree(CxJsonValue *value); |
927 void cxJsonValueFree(CxJsonValue *value); |
|
928 |
882 |
929 /** |
883 /** |
930 * Tries to obtain the next JSON value. |
884 * Tries to obtain the next JSON value. |
931 * |
885 * |
932 * Before this function can be called, the input buffer needs |
886 * Before this function can be called, the input buffer needs |
946 * @retval CX_JSON_BUFFER_ALLOC_FAILED allocating internal buffer space failed |
900 * @retval CX_JSON_BUFFER_ALLOC_FAILED allocating internal buffer space failed |
947 * @retval CX_JSON_VALUE_ALLOC_FAILED allocating memory for a CxJsonValue failed |
901 * @retval CX_JSON_VALUE_ALLOC_FAILED allocating memory for a CxJsonValue failed |
948 * @retval CX_JSON_FORMAT_ERROR_NUMBER the JSON text contains an illegally formatted number |
902 * @retval CX_JSON_FORMAT_ERROR_NUMBER the JSON text contains an illegally formatted number |
949 * @retval CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN JSON syntax error |
903 * @retval CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN JSON syntax error |
950 */ |
904 */ |
951 cx_attr_nonnull |
905 cx_attr_nonnull cx_attr_access_w(2) |
952 cx_attr_access_w(2) |
906 CX_EXPORT CxJsonStatus cxJsonNext(CxJson *json, CxJsonValue **value); |
953 cx_attr_export |
|
954 CxJsonStatus cxJsonNext(CxJson *json, CxJsonValue **value); |
|
955 |
907 |
956 /** |
908 /** |
957 * Checks if the specified value is a JSON object. |
909 * Checks if the specified value is a JSON object. |
958 * |
910 * |
959 * @param value a pointer to the value |
911 * @param value a pointer to the value |
960 * @retval true the value is a JSON object |
912 * @retval true the value is a JSON object |
961 * @retval false otherwise |
913 * @retval false otherwise |
962 */ |
914 */ |
963 cx_attr_nonnull |
915 cx_attr_nonnull |
964 static inline bool cxJsonIsObject(const CxJsonValue *value) { |
916 CX_INLINE bool cxJsonIsObject(const CxJsonValue *value) { |
965 return value->type == CX_JSON_OBJECT; |
917 return value->type == CX_JSON_OBJECT; |
966 } |
918 } |
967 |
919 |
968 /** |
920 /** |
969 * Checks if the specified value is a JSON array. |
921 * Checks if the specified value is a JSON array. |
971 * @param value a pointer to the value |
923 * @param value a pointer to the value |
972 * @retval true the value is a JSON array |
924 * @retval true the value is a JSON array |
973 * @retval false otherwise |
925 * @retval false otherwise |
974 */ |
926 */ |
975 cx_attr_nonnull |
927 cx_attr_nonnull |
976 static inline bool cxJsonIsArray(const CxJsonValue *value) { |
928 CX_INLINE bool cxJsonIsArray(const CxJsonValue *value) { |
977 return value->type == CX_JSON_ARRAY; |
929 return value->type == CX_JSON_ARRAY; |
978 } |
930 } |
979 |
931 |
980 /** |
932 /** |
981 * Checks if the specified value is a string. |
933 * Checks if the specified value is a string. |
983 * @param value a pointer to the value |
935 * @param value a pointer to the value |
984 * @retval true the value is a string |
936 * @retval true the value is a string |
985 * @retval false otherwise |
937 * @retval false otherwise |
986 */ |
938 */ |
987 cx_attr_nonnull |
939 cx_attr_nonnull |
988 static inline bool cxJsonIsString(const CxJsonValue *value) { |
940 CX_INLINE bool cxJsonIsString(const CxJsonValue *value) { |
989 return value->type == CX_JSON_STRING; |
941 return value->type == CX_JSON_STRING; |
990 } |
942 } |
991 |
943 |
992 /** |
944 /** |
993 * Checks if the specified value is a JSON number. |
945 * Checks if the specified value is a JSON number. |
999 * @retval true the value is a JSON number |
951 * @retval true the value is a JSON number |
1000 * @retval false otherwise |
952 * @retval false otherwise |
1001 * @see cxJsonIsInteger() |
953 * @see cxJsonIsInteger() |
1002 */ |
954 */ |
1003 cx_attr_nonnull |
955 cx_attr_nonnull |
1004 static inline bool cxJsonIsNumber(const CxJsonValue *value) { |
956 CX_INLINE bool cxJsonIsNumber(const CxJsonValue *value) { |
1005 return value->type == CX_JSON_NUMBER || value->type == CX_JSON_INTEGER; |
957 return value->type == CX_JSON_NUMBER || value->type == CX_JSON_INTEGER; |
1006 } |
958 } |
1007 |
959 |
1008 /** |
960 /** |
1009 * Checks if the specified value is an integer number. |
961 * Checks if the specified value is an integer number. |
1012 * @retval true the value is an integer number |
964 * @retval true the value is an integer number |
1013 * @retval false otherwise |
965 * @retval false otherwise |
1014 * @see cxJsonIsNumber() |
966 * @see cxJsonIsNumber() |
1015 */ |
967 */ |
1016 cx_attr_nonnull |
968 cx_attr_nonnull |
1017 static inline bool cxJsonIsInteger(const CxJsonValue *value) { |
969 CX_INLINE bool cxJsonIsInteger(const CxJsonValue *value) { |
1018 return value->type == CX_JSON_INTEGER; |
970 return value->type == CX_JSON_INTEGER; |
1019 } |
971 } |
1020 |
972 |
1021 /** |
973 /** |
1022 * Checks if the specified value is a JSON literal. |
974 * Checks if the specified value is a JSON literal. |
1029 * @see cxJsonIsTrue() |
981 * @see cxJsonIsTrue() |
1030 * @see cxJsonIsFalse() |
982 * @see cxJsonIsFalse() |
1031 * @see cxJsonIsNull() |
983 * @see cxJsonIsNull() |
1032 */ |
984 */ |
1033 cx_attr_nonnull |
985 cx_attr_nonnull |
1034 static inline bool cxJsonIsLiteral(const CxJsonValue *value) { |
986 CX_INLINE bool cxJsonIsLiteral(const CxJsonValue *value) { |
1035 return value->type == CX_JSON_LITERAL; |
987 return value->type == CX_JSON_LITERAL; |
1036 } |
988 } |
1037 |
989 |
1038 /** |
990 /** |
1039 * Checks if the specified value is a Boolean literal. |
991 * Checks if the specified value is a Boolean literal. |
1043 * @retval false otherwise |
995 * @retval false otherwise |
1044 * @see cxJsonIsTrue() |
996 * @see cxJsonIsTrue() |
1045 * @see cxJsonIsFalse() |
997 * @see cxJsonIsFalse() |
1046 */ |
998 */ |
1047 cx_attr_nonnull |
999 cx_attr_nonnull |
1048 static inline bool cxJsonIsBool(const CxJsonValue *value) { |
1000 CX_INLINE bool cxJsonIsBool(const CxJsonValue *value) { |
1049 return cxJsonIsLiteral(value) && value->value.literal != CX_JSON_NULL; |
1001 return cxJsonIsLiteral(value) && value->value.literal != CX_JSON_NULL; |
1050 } |
1002 } |
1051 |
1003 |
1052 /** |
1004 /** |
1053 * Checks if the specified value is @c true. |
1005 * Checks if the specified value is @c true. |
1060 * @retval false otherwise |
1012 * @retval false otherwise |
1061 * @see cxJsonIsBool() |
1013 * @see cxJsonIsBool() |
1062 * @see cxJsonIsFalse() |
1014 * @see cxJsonIsFalse() |
1063 */ |
1015 */ |
1064 cx_attr_nonnull |
1016 cx_attr_nonnull |
1065 static inline bool cxJsonIsTrue(const CxJsonValue *value) { |
1017 CX_INLINE bool cxJsonIsTrue(const CxJsonValue *value) { |
1066 return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_TRUE; |
1018 return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_TRUE; |
1067 } |
1019 } |
1068 |
1020 |
1069 /** |
1021 /** |
1070 * Checks if the specified value is @c false. |
1022 * Checks if the specified value is @c false. |
1077 * @retval false otherwise |
1029 * @retval false otherwise |
1078 * @see cxJsonIsBool() |
1030 * @see cxJsonIsBool() |
1079 * @see cxJsonIsTrue() |
1031 * @see cxJsonIsTrue() |
1080 */ |
1032 */ |
1081 cx_attr_nonnull |
1033 cx_attr_nonnull |
1082 static inline bool cxJsonIsFalse(const CxJsonValue *value) { |
1034 CX_INLINE bool cxJsonIsFalse(const CxJsonValue *value) { |
1083 return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_FALSE; |
1035 return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_FALSE; |
1084 } |
1036 } |
1085 |
1037 |
1086 /** |
1038 /** |
1087 * Checks if the specified value is @c null. |
1039 * Checks if the specified value is @c null. |
1090 * @retval true the value is @c null |
1042 * @retval true the value is @c null |
1091 * @retval false otherwise |
1043 * @retval false otherwise |
1092 * @see cxJsonIsLiteral() |
1044 * @see cxJsonIsLiteral() |
1093 */ |
1045 */ |
1094 cx_attr_nonnull |
1046 cx_attr_nonnull |
1095 static inline bool cxJsonIsNull(const CxJsonValue *value) { |
1047 CX_INLINE bool cxJsonIsNull(const CxJsonValue *value) { |
1096 return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_NULL; |
1048 return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_NULL; |
1097 } |
1049 } |
1098 |
1050 |
1099 /** |
1051 /** |
1100 * Obtains a C string from the given JSON value. |
1052 * Obtains a C string from the given JSON value. |
1103 * |
1055 * |
1104 * @param value the JSON value |
1056 * @param value the JSON value |
1105 * @return the value represented as C string |
1057 * @return the value represented as C string |
1106 * @see cxJsonIsString() |
1058 * @see cxJsonIsString() |
1107 */ |
1059 */ |
1108 cx_attr_nonnull |
1060 cx_attr_nonnull cx_attr_returns_nonnull |
1109 cx_attr_returns_nonnull |
1061 CX_EXPORT char *cxJsonAsString(const CxJsonValue *value); |
1110 static inline char *cxJsonAsString(const CxJsonValue *value) { |
|
1111 return value->value.string.ptr; |
|
1112 } |
|
1113 |
1062 |
1114 /** |
1063 /** |
1115 * Obtains a UCX string from the given JSON value. |
1064 * Obtains a UCX string from the given JSON value. |
1116 * |
1065 * |
1117 * If the @p value is not a string, the behavior is undefined. |
1066 * If the @p value is not a string, the behavior is undefined. |
1119 * @param value the JSON value |
1068 * @param value the JSON value |
1120 * @return the value represented as UCX string |
1069 * @return the value represented as UCX string |
1121 * @see cxJsonIsString() |
1070 * @see cxJsonIsString() |
1122 */ |
1071 */ |
1123 cx_attr_nonnull |
1072 cx_attr_nonnull |
1124 static inline cxstring cxJsonAsCxString(const CxJsonValue *value) { |
1073 CX_EXPORT cxstring cxJsonAsCxString(const CxJsonValue *value); |
1125 return cx_strcast(value->value.string); |
|
1126 } |
|
1127 |
1074 |
1128 /** |
1075 /** |
1129 * Obtains a mutable UCX string from the given JSON value. |
1076 * Obtains a mutable UCX string from the given JSON value. |
1130 * |
1077 * |
1131 * If the @p value is not a string, the behavior is undefined. |
1078 * If the @p value is not a string, the behavior is undefined. |
1133 * @param value the JSON value |
1080 * @param value the JSON value |
1134 * @return the value represented as mutable UCX string |
1081 * @return the value represented as mutable UCX string |
1135 * @see cxJsonIsString() |
1082 * @see cxJsonIsString() |
1136 */ |
1083 */ |
1137 cx_attr_nonnull |
1084 cx_attr_nonnull |
1138 static inline cxmutstr cxJsonAsCxMutStr(const CxJsonValue *value) { |
1085 CX_EXPORT cxmutstr cxJsonAsCxMutStr(const CxJsonValue *value); |
1139 return value->value.string; |
|
1140 } |
|
1141 |
1086 |
1142 /** |
1087 /** |
1143 * Obtains a double-precision floating-point value from the given JSON value. |
1088 * Obtains a double-precision floating-point value from the given JSON value. |
1144 * |
1089 * |
1145 * If the @p value is not a JSON number, the behavior is undefined. |
1090 * If the @p value is not a JSON number, the behavior is undefined. |
1147 * @param value the JSON value |
1092 * @param value the JSON value |
1148 * @return the value represented as double |
1093 * @return the value represented as double |
1149 * @see cxJsonIsNumber() |
1094 * @see cxJsonIsNumber() |
1150 */ |
1095 */ |
1151 cx_attr_nonnull |
1096 cx_attr_nonnull |
1152 static inline double cxJsonAsDouble(const CxJsonValue *value) { |
1097 CX_EXPORT double cxJsonAsDouble(const CxJsonValue *value); |
1153 if (value->type == CX_JSON_INTEGER) { |
|
1154 return (double) value->value.integer; |
|
1155 } else { |
|
1156 return value->value.number; |
|
1157 } |
|
1158 } |
|
1159 |
1098 |
1160 /** |
1099 /** |
1161 * Obtains a 64-bit signed integer from the given JSON value. |
1100 * Obtains a 64-bit signed integer from the given JSON value. |
1162 * |
1101 * |
1163 * If the @p value is not a JSON number, the behavior is undefined. |
1102 * If the @p value is not a JSON number, the behavior is undefined. |
1168 * @return the value represented as double |
1107 * @return the value represented as double |
1169 * @see cxJsonIsNumber() |
1108 * @see cxJsonIsNumber() |
1170 * @see cxJsonIsInteger() |
1109 * @see cxJsonIsInteger() |
1171 */ |
1110 */ |
1172 cx_attr_nonnull |
1111 cx_attr_nonnull |
1173 static inline int64_t cxJsonAsInteger(const CxJsonValue *value) { |
1112 CX_EXPORT int64_t cxJsonAsInteger(const CxJsonValue *value); |
1174 if (value->type == CX_JSON_INTEGER) { |
|
1175 return value->value.integer; |
|
1176 } else { |
|
1177 return (int64_t) value->value.number; |
|
1178 } |
|
1179 } |
|
1180 |
1113 |
1181 /** |
1114 /** |
1182 * Obtains a Boolean value from the given JSON value. |
1115 * Obtains a Boolean value from the given JSON value. |
1183 * |
1116 * |
1184 * If the @p value is not a JSON literal, the behavior is undefined. |
1117 * If the @p value is not a JSON literal, the behavior is undefined. |
1187 * @param value the JSON value |
1120 * @param value the JSON value |
1188 * @return the value represented as double |
1121 * @return the value represented as double |
1189 * @see cxJsonIsLiteral() |
1122 * @see cxJsonIsLiteral() |
1190 */ |
1123 */ |
1191 cx_attr_nonnull |
1124 cx_attr_nonnull |
1192 static inline bool cxJsonAsBool(const CxJsonValue *value) { |
1125 CX_INLINE bool cxJsonAsBool(const CxJsonValue *value) { |
1193 return value->value.literal == CX_JSON_TRUE; |
1126 return value->value.literal == CX_JSON_TRUE; |
1194 } |
1127 } |
1195 |
1128 |
1196 /** |
1129 /** |
1197 * Returns the size of a JSON array. |
1130 * Returns the size of a JSON array. |
1201 * @param value the JSON value |
1134 * @param value the JSON value |
1202 * @return the size of the array |
1135 * @return the size of the array |
1203 * @see cxJsonIsArray() |
1136 * @see cxJsonIsArray() |
1204 */ |
1137 */ |
1205 cx_attr_nonnull |
1138 cx_attr_nonnull |
1206 static inline size_t cxJsonArrSize(const CxJsonValue *value) { |
1139 CX_INLINE size_t cxJsonArrSize(const CxJsonValue *value) { |
1207 return value->value.array.array_size; |
1140 return value->value.array.array_size; |
1208 } |
1141 } |
1209 |
1142 |
1210 /** |
1143 /** |
1211 * Returns an element from a JSON array. |
1144 * Returns an element from a JSON array. |
1219 * @param value the JSON value |
1152 * @param value the JSON value |
1220 * @param index the index in the array |
1153 * @param index the index in the array |
1221 * @return the value at the specified index |
1154 * @return the value at the specified index |
1222 * @see cxJsonIsArray() |
1155 * @see cxJsonIsArray() |
1223 */ |
1156 */ |
1224 cx_attr_nonnull |
1157 cx_attr_nonnull cx_attr_returns_nonnull |
1225 cx_attr_returns_nonnull |
1158 CX_EXPORT CxJsonValue *cxJsonArrGet(const CxJsonValue *value, size_t index); |
1226 cx_attr_export |
|
1227 CxJsonValue *cxJsonArrGet(const CxJsonValue *value, size_t index); |
|
1228 |
1159 |
1229 /** |
1160 /** |
1230 * Removes an element from a JSON array. |
1161 * Removes an element from a JSON array. |
1231 * |
1162 * |
1232 * If the @p value is not a JSON array, the behavior is undefined. |
1163 * If the @p value is not a JSON array, the behavior is undefined. |
1238 * @param index the index in the array |
1169 * @param index the index in the array |
1239 * @return the removed value from the specified index or @c NULL when the index was out of bounds |
1170 * @return the removed value from the specified index or @c NULL when the index was out of bounds |
1240 * @see cxJsonIsArray() |
1171 * @see cxJsonIsArray() |
1241 */ |
1172 */ |
1242 cx_attr_nonnull |
1173 cx_attr_nonnull |
1243 cx_attr_export |
1174 CX_EXPORT CxJsonValue *cxJsonArrRemove(CxJsonValue *value, size_t index); |
1244 CxJsonValue *cxJsonArrRemove(CxJsonValue *value, size_t index); |
|
1245 |
1175 |
1246 /** |
1176 /** |
1247 * Returns an iterator over the JSON array elements. |
1177 * Returns an iterator over the JSON array elements. |
1248 * |
1178 * |
1249 * The iterator yields values of type @c CxJsonValue* . |
1179 * The iterator yields values of type @c CxJsonValue* . |
1252 * |
1182 * |
1253 * @param value the JSON value |
1183 * @param value the JSON value |
1254 * @return an iterator over the array elements |
1184 * @return an iterator over the array elements |
1255 * @see cxJsonIsArray() |
1185 * @see cxJsonIsArray() |
1256 */ |
1186 */ |
1257 cx_attr_nonnull |
1187 cx_attr_nonnull cx_attr_nodiscard |
1258 cx_attr_nodiscard |
1188 CX_EXPORT CxIterator cxJsonArrIter(const CxJsonValue *value); |
1259 cx_attr_export |
|
1260 CxIterator cxJsonArrIter(const CxJsonValue *value); |
|
1261 |
1189 |
1262 /** |
1190 /** |
1263 * Returns an iterator over the JSON object members. |
1191 * Returns an iterator over the JSON object members. |
1264 * |
1192 * |
1265 * The iterator yields values of type @c CxJsonObjValue* which |
1193 * The iterator yields values of type @c CxJsonObjValue* which |
1269 * |
1197 * |
1270 * @param value the JSON value |
1198 * @param value the JSON value |
1271 * @return an iterator over the object members |
1199 * @return an iterator over the object members |
1272 * @see cxJsonIsObject() |
1200 * @see cxJsonIsObject() |
1273 */ |
1201 */ |
1274 cx_attr_nonnull |
1202 cx_attr_nonnull cx_attr_nodiscard |
1275 cx_attr_nodiscard |
1203 CX_EXPORT CxIterator cxJsonObjIter(const CxJsonValue *value); |
1276 cx_attr_export |
|
1277 CxIterator cxJsonObjIter(const CxJsonValue *value); |
|
1278 |
1204 |
1279 /** |
1205 /** |
1280 * Internal function, do not use. |
1206 * Internal function, do not use. |
1281 * @param value the JSON object |
1207 * @param value the JSON object |
1282 * @param name the key to look up |
1208 * @param name the key to look up |
1283 * @return the value corresponding to the key |
1209 * @return the value corresponding to the key |
1284 */ |
1210 */ |
1285 cx_attr_nonnull |
1211 cx_attr_nonnull cx_attr_returns_nonnull |
1286 cx_attr_returns_nonnull |
1212 CX_EXPORT CxJsonValue *cx_json_obj_get(const CxJsonValue *value, cxstring name); |
1287 cx_attr_export |
|
1288 CxJsonValue *cx_json_obj_get(const CxJsonValue *value, cxstring name); |
|
1289 |
1213 |
1290 /** |
1214 /** |
1291 * Returns a value corresponding to a key in a JSON object. |
1215 * Returns a value corresponding to a key in a JSON object. |
1292 * |
1216 * |
1293 * If the @p value is not a JSON object, the behavior is undefined. |
1217 * If the @p value is not a JSON object, the behavior is undefined. |
1308 * @param value the JSON object |
1232 * @param value the JSON object |
1309 * @param name the key to look up |
1233 * @param name the key to look up |
1310 * @return the value corresponding to the key or @c NULL when the key is not part of the object |
1234 * @return the value corresponding to the key or @c NULL when the key is not part of the object |
1311 */ |
1235 */ |
1312 cx_attr_nonnull |
1236 cx_attr_nonnull |
1313 cx_attr_export |
1237 CX_EXPORT CxJsonValue *cx_json_obj_remove(CxJsonValue *value, cxstring name); |
1314 CxJsonValue *cx_json_obj_remove(CxJsonValue *value, cxstring name); |
|
1315 |
1238 |
1316 /** |
1239 /** |
1317 * Removes and returns a value corresponding to a key in a JSON object. |
1240 * Removes and returns a value corresponding to a key in a JSON object. |
1318 * |
1241 * |
1319 * If the @p value is not a JSON object, the behavior is undefined. |
1242 * If the @p value is not a JSON object, the behavior is undefined. |