Mercurial > hg > nginx-site

comparison xml/en/docs/njs/reference.xml @ 2569:2edc64c05b0e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Removed ECMAScript methods from njs Reference.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 14 Jul 2020 16:44:46 +0100
parents 5aa57c656cbf
children 44792f1ee284
comparison
equal deleted inserted replaced
2568:aa015272ea32 2569:2edc64c05b0e
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> 7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
8 8
9 <article name="Reference" 9 <article name="Reference"
10 link="/en/docs/njs/reference.html" 10 link="/en/docs/njs/reference.html"
11 lang="en" 11 lang="en"
12 rev="45"> 12 rev="46">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 <link doc="index.xml">njs</link> provides objects, methods and properties 17 <link doc="index.xml">njs</link> provides objects, methods and properties
18 for extending nginx functionality. 18 for extending nginx functionality.
19 </para>
20
21 <para>
22 This reference contains only njs specific properties, methods and modules
23 not compliant with ECMAScript.
24 Definitions of njs properties and methods compliant with ECMAScript
25 can be found in
26 <link url="http://www.ecma-international.org/ecma-262/">ECMAScript
27 specification</link>.
28 List of all njs properties and methods can be found in
29 <link doc="compatibility.xml">Compatibility</link>.
19 </para> 30 </para>
20 31
21 </section> 32 </section>
22 33
23 34
544 </section> 555 </section>
545 556
546 </section> 557 </section>
547 558
548 559
549 <section id="core_object" name="Object">
550
551 <para>
552 The <literal>Object</literal> constructor corresponds to a standard JS object.
553 <list type="tag">
554
555 <tag-name id="object_entries"><literal>Object.entries(<value>object</value>)</literal></tag-name>
556 <tag-desc>
557 returns an array of all enumerable property
558 <literal>[key, value]</literal> pairs
559 of the given <literal>object</literal>
560 (<link doc="changes.xml" id="njs0.2.7">0.2.7</link>).
561 </tag-desc>
562
563 <tag-name id="object_values"><literal>Object.values(<value>object</value>)</literal></tag-name>
564 <tag-desc>
565 returns an array of all enumerable property values
566 of the given <literal>object</literal>
567 (<link doc="changes.xml" id="njs0.2.7">0.2.7</link>).
568 </tag-desc>
569
570 </list>
571 </para>
572
573 </section>
574
575
576 <section id="string" name="String"> 560 <section id="string" name="String">
577 561
578 <para> 562 <para>
579 There are two types of strings in njs: a Unicode string (default) and 563 There are two types of strings in njs: a Unicode string (default) and
580 a byte string. 564 a byte string.
620 <list type="tag"> 604 <list type="tag">
621 605
622 <tag-name id="string_bytesfrom"><literal>String.bytesFrom(<value>array</value> 606 <tag-name id="string_bytesfrom"><literal>String.bytesFrom(<value>array</value>
623 | <value>string</value>, <value>encoding</value>)</literal></tag-name> 607 | <value>string</value>, <value>encoding</value>)</literal></tag-name>
624 <tag-desc> 608 <tag-desc>
625 (njs specific) Creates a byte string either from an array that contains octets, 609 Creates a byte string either from an array that contains octets,
626 or from an encoded string 610 or from an encoded string
627 (<link doc="changes.xml" id="njs0.2.3">0.2.3</link>). 611 (<link doc="changes.xml" id="njs0.2.3">0.2.3</link>).
628 The encoding can be 612 The encoding can be
629 <literal>hex</literal>, 613 <literal>hex</literal>,
630 <literal>base64</literal>, and 614 <literal>base64</literal>, and
636 >> String.bytesFrom('YnVmZmVy', 'base64') 620 >> String.bytesFrom('YnVmZmVy', 'base64')
637 'buffer' 621 'buffer'
638 </example> 622 </example>
639 </tag-desc> 623 </tag-desc>
640 624
641 <tag-name id="string_fromcharcode"><literal>String.fromCharCode(<value>CharCode1</value>[, ...[,
642 <value>CharCodeN</value>]])</literal></tag-name>
643 <tag-desc>
644 Returns a string from one or more Unicode code points.
645 <example>
646 >> String.fromCharCode(97, 98, 99, 100)
647 'abcd'
648 </example>
649 </tag-desc>
650
651 <tag-name id="string_fromcodepoint"><literal>String.fromCodePoint(<value>codePoint1</value>[, ...[,
652 <value>codePoint2</value>]])</literal></tag-name>
653 <tag-desc>
654 Returns a string from one or more Unicode code points.
655 <example>
656 >> String.fromCodePoint(97, 98, 99, 100)
657 'abcd'
658 </example>
659 </tag-desc>
660
661 <tag-name id="string_charat"><literal>String.prototype.charAt(<value>index</value>)</literal></tag-name>
662 <tag-desc>
663 Returns a string representing one Unicode code unit
664 at the specified <literal>index</literal>;
665 empty string if index is out of range.
666 The index can be an integer
667 between 0 and 1-less-than the length of the string.
668 If no index is provided, the default is <literal>0</literal>,
669 so the first character in the string is returned.
670 </tag-desc>
671
672 <tag-name id="string_codepointat"><literal>String.prototype.CodePointAt(<value>position</value>)</literal></tag-name>
673 <tag-desc>
674 Returns a number representing the code point value of the character
675 at the given <literal>position</literal>;
676 <literal>undefined</literal> if there is no element at position.
677 <example>
678 >> 'ABCD'.codePointAt(3);
679 68
680 </example>
681 </tag-desc>
682
683 <tag-name id="string_concat"><literal>String.prototype.concat(<value>string1</value>[, ...,
684 <value>stringN</value>])</literal></tag-name>
685 <tag-desc>
686 Returns a string that contains the concatenation of specified
687 <literal>strings</literal>.
688 <example>
689 >> "a".concat("b", "c")
690 'abc'
691 </example>
692 </tag-desc>
693
694 <tag-name id="string_endswith"><literal>String.prototype.endsWith(<value>searchString</value>[,
695 <value>length</value>])</literal></tag-name>
696 <tag-desc>
697 Returns <literal>true</literal> if a string ends with the characters
698 of a specified string, otherwise <literal>false</literal>.
699 The optional <literal>length</literal> parameter is the the length of string.
700 If omitted, the default value is the length of the string.
701 <example>
702 >> 'abc'.endsWith('abc')
703 true
704 >> 'abca'.endsWith('abc')
705 false
706 </example>
707 </tag-desc>
708
709 <tag-name id="string_frombytes"><literal>String.prototype.fromBytes(<value>start</value>[, 625 <tag-name id="string_frombytes"><literal>String.prototype.fromBytes(<value>start</value>[,
710 <value>end</value>])</literal></tag-name> 626 <value>end</value>])</literal></tag-name>
711 <tag-desc> 627 <tag-desc>
712 (njs specific) Returns a new Unicode string from a byte string 628 Returns a new Unicode string from a byte string
713 where each byte is replaced with a corresponding Unicode code point. 629 where each byte is replaced with a corresponding Unicode code point.
714 </tag-desc> 630 </tag-desc>
715 631
716 <tag-name id="string_fromutf8"><literal>String.prototype.fromUTF8(<value>start</value>[, 632 <tag-name id="string_fromutf8"><literal>String.prototype.fromUTF8(<value>start</value>[,
717 <value>end</value>])</literal></tag-name> 633 <value>end</value>])</literal></tag-name>
718 <tag-desc> 634 <tag-desc>
719 (njs specific) Converts a byte string containing a valid UTF8 string 635 Converts a byte string containing a valid UTF8 string
720 into a Unicode string, 636 into a Unicode string,
721 otherwise <literal>null</literal> is returned. 637 otherwise <literal>null</literal> is returned.
722 </tag-desc> 638 </tag-desc>
723 639
724 <tag-name id="string_includes"><literal>String.prototype.includes(<value>searchString</value>[,
725 <value>position</value>]))</literal></tag-name>
726 <tag-desc>
727 Returns <literal>true</literal> if a string is found within another string,
728 otherwise <literal>false</literal>.
729 The optional <literal>position</literal> parameter is the position
730 within the string at which to begin search for <literal>searchString</literal>.
731 Default value is 0.
732 <example>
733 >> 'abc'.includes('bc')
734 true
735 </example>
736 </tag-desc>
737
738 <tag-name id="string_indexof"><literal>String.prototype.indexOf(<value>searchString</value>[,
739 <value>fromIndex</value>])</literal></tag-name>
740 <tag-desc>
741 Returns the position of the first occurrence
742 of the <literal>searchString</literal>.
743 The search is started at <literal>fromIndex</literal>.
744 Returns <value>-1</value> if the value is not found.
745 The <literal>fromIndex</literal> is an integer,
746 default value is 0.
747 If <literal>fromIndex</literal> is lower than 0
748 or greater than
749 <link id="string_length">String.prototype.length</link><value></value>,
750 the search starts at index <value>0</value> and
751 <value>String.prototype.length</value>.
752 <example>
753 >> 'abcdef'.indexOf('de', 2)
754 3
755 </example>
756 </tag-desc>
757
758 <tag-name id="string_lastindexof"><literal>String.prototype.lastIndexOf(<value>searchString</value>[,
759 <value>fromIndex</value>])</literal></tag-name>
760 <tag-desc>
761 Returns the position of the last occurrence
762 of the <literal>searchString</literal>,
763 searching backwards from <literal>fromIndex</literal>.
764 Returns <value>-1</value> if the value is not found.
765 If <literal>searchString</literal> is empty,
766 then <literal>fromIndex</literal> is returned.
767 <example>
768 >> "nginx".lastIndexOf("gi")
769 1
770 </example>
771 </tag-desc>
772
773 <tag-name id="string_length"><literal>String.prototype.length</literal></tag-name>
774 <tag-desc>
775 Returns the length of the string.
776 <example>
777 >> 'αβγδ'.length
778 4
779 </example>
780 </tag-desc>
781
782 <tag-name id="string_match"><literal>String.prototype.match([<value>regexp</value>])</literal></tag-name>
783 <tag-desc>
784 Matches a string against a <literal>regexp</literal>.
785 <example>
786 >> 'nginx'.match( /ng/i )
787 'ng'
788 </example>
789 </tag-desc>
790
791 <tag-name id="string_padend"><literal>String.prototype.padEnd(<value>length</value>
792 [, <value>string</value>])</literal></tag-name>
793 <tag-desc>
794 Returns a string of a specified <literal>length</literal>
795 with the pad <literal>string</literal> applied to the end of the specified
796 string (<link doc="changes.xml" id="njs0.2.3">0.2.3</link>).
797 <example>
798 >> '1234'.padEnd(8, 'abcd')
799 '1234abcd'
800 </example>
801 </tag-desc>
802
803 <tag-name id="string_padstart"><literal>String.prototype.padStart(<value>length</value>
804 [, <value>string</value>])</literal></tag-name>
805 <tag-desc>
806 Returns a string of a specified <literal>length</literal>
807 with the pad <literal>string</literal> applied to the start of the specified
808 string (<link doc="changes.xml" id="njs0.2.3">0.2.3</link>).
809 <example>
810 >> '1234'.padStart(8, 'abcd')
811 'abcd1234'
812 </example>
813 </tag-desc>
814
815 <tag-name id="string_repeat"><literal>String.prototype.repeat(<value>number</value>)</literal></tag-name>
816 <tag-desc>
817 Returns a string
818 with the specified <literal>number</literal> of copies of the string.
819 <example>
820 >> 'abc'.repeat(3)
821 'abcabcabc'
822 </example>
823 </tag-desc>
824
825 <tag-name id="string_replace"><literal>String.prototype.replace([<value>regexp</value>|<value>string</value>[,
826 <value>string</value>|<value>function</value>]])</literal></tag-name>
827 <tag-desc>
828 Returns a new string with matches of a pattern
829 (<literal>string</literal> or a <literal>regexp</literal>)
830 replaced by a <literal>string</literal> or a <literal>function</literal>.
831 <example>
832 >> 'abcdefgh'.replace('d', 1)
833 'abc1efgh'
834 </example>
835 </tag-desc>
836
837 <tag-name id="string_search"><literal>String.prototype.search([<value>regexp</value>])</literal></tag-name>
838 <tag-desc>
839 Searches for a string using a <literal>regexp</literal>
840 <example>
841 >> 'abcdefgh'.search('def')
842 3
843 </example>
844 </tag-desc>
845
846 <tag-name id="string_slice"><literal>String.prototype.slice(<value>start</value>[,
847 <value>end</value>])</literal></tag-name>
848 <tag-desc>
849 Returns a new string containing a part of an
850 original string between <literal>start</literal>
851 and <literal>end</literal> or
852 from <literal>start</literal> to the end of the string.
853 <example>
854 >> 'abcdefghijklmno'.slice(NaN, 5)
855 'abcde'
856 </example>
857 </tag-desc>
858
859 <tag-name id="string_split"><literal>String.prototype.split(([<value>string</value>|<value>regexp</value>[,
860 <value>limit</value>]]))</literal></tag-name>
861 <tag-desc>
862 Returns match of a string against a <literal>regexp</literal>.
863 The optional <literal>limit</literal> parameter is an integer that specifies
864 a limit on the number of splits to be found.
865 <example>
866 >> 'abc'.split('')
867 [
868 'a',
869 'b',
870 'c'
871 ]
872 </example>
873 </tag-desc>
874
875 <tag-name id="string_startswith"><literal>String.prototype.startsWith(<value>searchString</value>[,
876 <value>position</value>])</literal></tag-name>
877 <tag-desc>
878 Returns <literal>true</literal> if a string begins with the characters
879 of a specified string, otherwise <literal>false</literal>.
880 The optional <literal>position</literal> parameter is the position
881 in this string at which to begin search for <literal>searchString</literal>.
882 Default value is 0.
883 <example>
884 >> 'abc'.startsWith('abc')
885 true
886 > 'aabc'.startsWith('abc')
887 false
888 </example>
889 </tag-desc>
890
891 <tag-name id="string_substr"><literal>String.prototype.substr(<value>start</value>[,
892 <value>length</value>])</literal></tag-name>
893 <tag-desc>
894 Returns the part of the string of the specified <literal>length</literal>
895 from <literal>start</literal>
896 or from <literal>start</literal> to the end of the string.
897 <example>
898 >> 'abcdefghijklmno'.substr(3, 5)
899 'defgh'
900 </example>
901 </tag-desc>
902
903 <tag-name id="string_substring"><literal>String.prototype.substring(<value>start</value>[,
904 <value>end</value>])</literal></tag-name>
905 <tag-desc>
906 Returns the part of the string between
907 <literal>start</literal> and <literal>end</literal> or
908 from <literal>start</literal> to the end of the string.
909 <example>
910 >> 'abcdefghijklmno'.substring(3, 5)
911 'de'
912 </example>
913 </tag-desc>
914
915 <tag-name id="string_tobytes"><literal>String.prototype.toBytes(start[, 640 <tag-name id="string_tobytes"><literal>String.prototype.toBytes(start[,
916 end])</literal></tag-name> 641 end])</literal></tag-name>
917 <tag-desc> 642 <tag-desc>
918 (njs specific) Serializes a Unicode string to a byte string. 643 Serializes a Unicode string to a byte string.
919 Returns <literal>null</literal> if a character larger than 255 is 644 Returns <literal>null</literal> if a character larger than 255 is
920 found in the string. 645 found in the string.
921 </tag-desc> 646 </tag-desc>
922 647
923 <tag-name id="string_tolowercase"><literal>String.prototype.toLowerCase()</literal></tag-name>
924 <tag-desc>
925 Converts a string to lower case.
926 The method supports only simple Unicode folding.
927 <example>
928 >> 'ΑΒΓΔ'.toLowerCase()
929 'αβγδ'
930 </example>
931 </tag-desc>
932
933 <tag-name><literal>String.prototype.toString([<value>encoding</value>])</literal></tag-name> 648 <tag-name><literal>String.prototype.toString([<value>encoding</value>])</literal></tag-name>
934 <tag-desc> 649 <tag-desc>
935 <para> 650 <para>
936 If no <literal>encoding</literal> is specified, 651 If no <literal>encoding</literal> is specified,
937 returns a specified Unicode string or byte string as in ECMAScript. 652 returns a specified Unicode string or byte string as in ECMAScript.
938 </para> 653 </para>
939 654
940 <para> 655 <para>
941 (njs specific) If <literal>encoding</literal> is specified, 656 If <literal>encoding</literal> is specified,
942 encodes a <link id="string_tobytes">byte string</link> to 657 encodes a <link id="string_tobytes">byte string</link> to
943 <literal>hex</literal>, 658 <literal>hex</literal>,
944 <literal>base64</literal>, or 659 <literal>base64</literal>, or
945 <literal>base64url</literal>. 660 <literal>base64url</literal>.
946 </para> 661 </para>
948 >> 'αβγδ'.toUTF8().toString('base64url') 663 >> 'αβγδ'.toUTF8().toString('base64url')
949 'zrHOss6zzrQ' 664 'zrHOss6zzrQ'
950 </example> 665 </example>
951 </tag-desc> 666 </tag-desc>
952 667
953 <tag-name id="string_touppercase"><literal>String.prototype.toUpperCase()</literal></tag-name>
954 <tag-desc>
955 Converts a string to upper case.
956 The method supports only simple Unicode folding.
957 <example>
958 >> 'αβγδ'.toUpperCase()
959 'ΑΒΓΔ'
960 </example>
961 </tag-desc>
962
963 <tag-name id="string_toutf8"><literal>String.prototype.toUTF8(<value>start</value>[, 668 <tag-name id="string_toutf8"><literal>String.prototype.toUTF8(<value>start</value>[,
964 <value>end</value>])</literal></tag-name> 669 <value>end</value>])</literal></tag-name>
965 <tag-desc> 670 <tag-desc>
966 (njs specific) Serializes a Unicode string 671 Serializes a Unicode string
967 to a byte string using UTF8 encoding. 672 to a byte string using UTF8 encoding.
968 <example> 673 <example>
969 >> 'αβγδ'.toUTF8().length 674 >> 'αβγδ'.toUTF8().length
970 8 675 8
971 >> 'αβγδ'.length 676 >> 'αβγδ'.length
972 4 677 4
973 </example> 678 </example>
974 </tag-desc> 679 </tag-desc>
975 680
976 <tag-name id="string_trim"><literal>String.prototype.trim()</literal></tag-name> 681 </list>
977 <tag-desc>
978 Removes whitespaces from both ends of a string.
979 <example>
980 >> ' abc '.trim()
981 'abc'
982 </example>
983 </tag-desc>
984
985 <tag-name id="string_trimend"><literal>String.prototype.trimEnd()</literal></tag-name>
986 <tag-desc>
987 Removes whitespaces from the end of a string
988 (<link doc="changes.xml" id="njs0.3.4">0.3.4</link>).
989 <example>
990 >> ' abc '.trimEnd()
991 ' abc'
992 </example>
993 </tag-desc>
994
995 <tag-name id="string_trimstart"><literal>String.prototype.trimStart()</literal></tag-name>
996 <tag-desc>
997 Removes whitespaces from the beginning of a string
998 (<link doc="changes.xml" id="njs0.3.4">0.3.4</link>).
999 <example>
1000 >> ' abc '.trimStart()
1001 'abc '
1002 </example>
1003 </tag-desc>
1004
1005 <tag-name id="encodeuri"><literal>encodeURI(<value>URI</value>)</literal></tag-name>
1006 <tag-desc>
1007 Encodes a URI by replacing each instance of certain characters
1008 by one, two, three, or four escape sequences
1009 representing the UTF-8 encoding of the character
1010 <example>
1011 >> encodeURI('012αβγδ')
1012 '012%CE%B1%CE%B2%CE%B3%CE%B4'
1013 </example>
1014 </tag-desc>
1015
1016 <tag-name id="encodeuricomponent"><literal>encodeURIComponent(<value>encodedURIString</value>)</literal></tag-name>
1017 <tag-desc>
1018 Encodes a URI by replacing each instance of certain characters
1019 by one, two, three, or four escape sequences
1020 representing the UTF-8 encoding of the character.
1021 <example>
1022 >> encodeURIComponent('[@?=')
1023 '%5B%40%3F%3D'
1024 </example>
1025 </tag-desc>
1026
1027 <tag-name id="decodeuri"><literal>decodeURI(<value>encodedURI</value>)</literal></tag-name>
1028 <tag-desc>
1029 Decodes a previously <link id="encodeuri">encoded</link> URI.
1030 <example>
1031 >> decodeURI('012%CE%B1%CE%B2%CE%B3%CE%B4')
1032 '012αβγδ'
1033 </example>
1034 </tag-desc>
1035
1036 <tag-name id="decodeuricomponent"><literal>decodeURIComponent(<value>decodedURIString</value>)</literal></tag-name>
1037 <tag-desc>
1038 Decodes an encoded component of a previously encoded URI.
1039 <example>
1040 >> decodeURIComponent('%5B%40%3F%3D')
1041 '[@?='
1042 </example>
1043 </tag-desc>
1044
1045 </list>
1046 </para>
1047
1048 </section>
1049
1050
1051 <section id="core_typedarray" name="TypedArray">
1052
1053 <para>
1054 <literal>TypedArray</literal> is a number of different global properties
1055 whose values are typed array constructors for specific element types.
1056 <list type="tag">
1057
1058 <tag-name id="array_sort"><literal>TypedArray.prototype.sort()</literal></tag-name>
1059 <tag-desc>
1060 sorts the elements of a typed array numerically
1061 and returns the updated typed array
1062 (<link doc="changes.xml" id="njs0.4.2">0.4.2</link>).
1063 </tag-desc>
1064 </list>
1065 </para>
1066
1067 </section>
1068
1069
1070 <section id="core_json" name="JSON">
1071
1072 <para>
1073 The <literal>JSON</literal> object (ES 5.1) provides functions
1074 to convert njs values to and from JSON format.
1075 <list type="tag">
1076
1077 <tag-name id="core_json_parse"><literal>JSON.parse(<value>string</value>[,
1078 <value>reviver</value>])</literal></tag-name>
1079 <tag-desc>
1080 Converts a <literal>string</literal> that represents JSON data
1081 into an njs object (<literal>{...}</literal>) or
1082 array (<literal>[...]</literal>).
1083 The optional <literal>reviver</literal> parameter is a function (key, value)
1084 that will be called for each (key,value) pair and can transform the value.
1085 </tag-desc>
1086
1087 <tag-name id="core_json_stringify"><literal>JSON.stringify(<value>value</value>[,
1088 <value>replacer</value>] [, <value>space</value>])</literal></tag-name>
1089 <tag-desc>
1090 Converts an njs object back to JSON.
1091 The obligatory <literal>value</literal> parameter is generally a JSON
1092 <literal>object</literal> or <literal>array</literal> that will be converted.
1093 If the value has a <literal>toJSON()</literal> method,
1094 it defines how the object will be serialized.
1095 The optional <literal>replacer</literal> parameter is
1096 a <literal>function</literal> or <literal>array</literal>
1097 that transforms results.
1098 The optional <literal>space</literal> parameter is
1099 a <literal>string</literal> or <literal>number</literal>.
1100 If it is a <literal>number</literal>,
1101 it indicates the number of white spaces placed before a result
1102 (no more than 10).
1103 If it is a <literal>string</literal>,
1104 it is used as a white space (or first 10 characters of it).
1105 If omitted or is <literal>null</literal>, no white space is used.
1106 </tag-desc>
1107 </list>
1108 </para>
1109
1110 <para>
1111 <example>
1112 >> var json = JSON.parse('{"a":1, "b":true}')
1113 >> json.a
1114 1
1115
1116 >> JSON.stringify(json)
1117 '{"a":1,"b":true}'
1118
1119 >> JSON.stringify({ x: [10, undefined, function(){}] })
1120 '{"x":[10,null,null]}'
1121
1122 >> JSON.stringify({"a":1, "toJSON": function() {return "xxx"}})
1123 '"xxx"'
1124
1125 # Example with function replacer
1126
1127 >> function replacer(key, value) {return (typeof value === 'string') ? undefined : value}
1128 >>JSON.stringify({a:1, b:"b", c:true}, replacer)
1129 '{"a":1,"c":true}'
1130 </example>
1131 </para> 682 </para>
1132 683
1133 </section> 684 </section>
1134 685
1135 686