src/cx/json.h

changeset 1426
3a89b31f0724
parent 1424
563033aa998c
equal deleted inserted replaced
1425:83284b289430 1426:3a89b31f0724
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.

mercurial