Merge pull request #4267 from TDT-AG/pr/20200713-luci-app-statistics
[project/luci.git] / docs / api / modules / luci.ip.cidr.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html>
4 <head>
5 <title>Reference</title>
6 <link rel="stylesheet" href="../luadoc.css" type="text/css" />
7 <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/-->
8 </head>
9
10 <body>
11 <div id="container">
12
13 <div id="product">
14 <div id="product_logo"></div>
15 <div id="product_name"><big><b></b></big></div>
16 <div id="product_description"></div>
17 </div> <!-- id="product" -->
18
19 <div id="main">
20
21 <div id="navigation">
22
23
24 <h1>LuaDoc</h1>
25 <ul>
26
27 <li><a href="../index.html">Index</a></li>
28
29 </ul>
30
31
32 <!-- Module list -->
33
34 <h1>Modules</h1>
35 <ul>
36
37 <li>
38 <a href="../modules/luci.dispatcher.html">luci.dispatcher</a>
39 </li>
40
41 <li>
42 <a href="../modules/luci.http.html">luci.http</a>
43 </li>
44
45 <li>
46 <a href="../modules/luci.http.conditionals.html">luci.http.conditionals</a>
47 </li>
48
49 <li>
50 <a href="../modules/luci.http.date.html">luci.http.date</a>
51 </li>
52
53 <li>
54 <a href="../modules/luci.http.mime.html">luci.http.mime</a>
55 </li>
56
57 <li>
58 <a href="../modules/luci.i18n.html">luci.i18n</a>
59 </li>
60
61 <li>
62 <a href="../modules/luci.ip.html">luci.ip</a>
63 </li>
64
65 <li><strong>luci.ip.cidr</strong></li>
66
67 <li>
68 <a href="../modules/luci.json.html">luci.json</a>
69 </li>
70
71 <li>
72 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
73 </li>
74
75 <li>
76 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
77 </li>
78
79 <li>
80 <a href="../modules/luci.model.ipkg.html">luci.model.ipkg</a>
81 </li>
82
83 <li>
84 <a href="../modules/luci.model.uci.html">luci.model.uci</a>
85 </li>
86
87 <li>
88 <a href="../modules/luci.rpcc.html">luci.rpcc</a>
89 </li>
90
91 <li>
92 <a href="../modules/luci.rpcc.ruci.html">luci.rpcc.ruci</a>
93 </li>
94
95 <li>
96 <a href="../modules/luci.sys.html">luci.sys</a>
97 </li>
98
99 <li>
100 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
101 </li>
102
103 <li>
104 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
105 </li>
106
107 <li>
108 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
109 </li>
110
111 <li>
112 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
113 </li>
114
115 <li>
116 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
117 </li>
118
119 <li>
120 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
121 </li>
122
123 <li>
124 <a href="../modules/luci.util.html">luci.util</a>
125 </li>
126
127 <li>
128 <a href="../modules/luci.xml.html">luci.xml</a>
129 </li>
130
131 <li>
132 <a href="../modules/nixio.html">nixio</a>
133 </li>
134
135 <li>
136 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
137 </li>
138
139 <li>
140 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
141 </li>
142
143 <li>
144 <a href="../modules/nixio.File.html">nixio.File</a>
145 </li>
146
147 <li>
148 <a href="../modules/nixio.README.html">nixio.README</a>
149 </li>
150
151 <li>
152 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
153 </li>
154
155 <li>
156 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
157 </li>
158
159 <li>
160 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
161 </li>
162
163 <li>
164 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
165 </li>
166
167 <li>
168 <a href="../modules/nixio.bin.html">nixio.bin</a>
169 </li>
170
171 <li>
172 <a href="../modules/nixio.bit.html">nixio.bit</a>
173 </li>
174
175 <li>
176 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
177 </li>
178
179 <li>
180 <a href="../modules/nixio.fs.html">nixio.fs</a>
181 </li>
182
183 </ul>
184
185
186
187 <!-- File list -->
188
189
190
191
192
193
194
195 </div><!-- id="navigation" -->
196
197 <div id="content">
198
199 <h1>Object Instance <code>luci.ip.cidr</code></h1>
200
201 <p>
202 IP CIDR Object.
203 Represents an IPv4 or IPv6 address range.</p>
204
205
206
207
208
209
210
211 <h2>Functions</h2>
212 <table class="function_list">
213
214 <tr>
215 <td class="name" nowrap><a href="#cidr.is4">cidr:is4</a>&nbsp;()</td>
216 <td class="summary">
217
218 Checks whether the CIDR instance is an IPv4 address range
219 </td>
220 </tr>
221
222 <tr>
223 <td class="name" nowrap><a href="#cidr.is4rfc1918">cidr:is4rfc1918</a>&nbsp;()</td>
224 <td class="summary">
225
226 Checks whether the CIDR instance is within the private RFC1918 address space
227 </td>
228 </tr>
229
230 <tr>
231 <td class="name" nowrap><a href="#cidr.is4linklocal">cidr:is4linklocal</a>&nbsp;()</td>
232 <td class="summary">
233
234 Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address
235 </td>
236 </tr>
237
238 <tr>
239 <td class="name" nowrap><a href="#cidr.is6">cidr:is6</a>&nbsp;()</td>
240 <td class="summary">
241
242 Checks whether the CIDR instance is an IPv6 address range
243 </td>
244 </tr>
245
246 <tr>
247 <td class="name" nowrap><a href="#cidr.is6linklocal">cidr:is6linklocal</a>&nbsp;()</td>
248 <td class="summary">
249
250 Checks whether the CIDR instance is an IPv6 link local address
251 </td>
252 </tr>
253
254 <tr>
255 <td class="name" nowrap><a href="#cidr.is6mapped4">cidr:is6mapped4</a>&nbsp;()</td>
256 <td class="summary">
257
258 Checks whether the CIDR instance is an IPv6 mapped IPv4 address
259 </td>
260 </tr>
261
262 <tr>
263 <td class="name" nowrap><a href="#cidr.ismac">cidr:ismac</a>&nbsp;()</td>
264 <td class="summary">
265
266 Checks whether the CIDR instance is an ethernet MAC address range
267 </td>
268 </tr>
269
270 <tr>
271 <td class="name" nowrap><a href="#cidr.ismaclocal">cidr:ismaclocal</a>&nbsp;()</td>
272 <td class="summary">
273
274 Checks whether the CIDR instance is a locally administered (LAA) MAC address
275 </td>
276 </tr>
277
278 <tr>
279 <td class="name" nowrap><a href="#cidr.ismacmcast">cidr:ismacmcast</a>&nbsp;()</td>
280 <td class="summary">
281
282 Checks whether the CIDR instance is a multicast MAC address
283 </td>
284 </tr>
285
286 <tr>
287 <td class="name" nowrap><a href="#cidr.lower">cidr:lower</a>&nbsp;(addr)</td>
288 <td class="summary">
289
290 Checks whether this CIDR instance is lower than the given argument.</td>
291 </tr>
292
293 <tr>
294 <td class="name" nowrap><a href="#cidr.higher">cidr:higher</a>&nbsp;(addr)</td>
295 <td class="summary">
296
297 Checks whether this CIDR instance is higher than the given argument.</td>
298 </tr>
299
300 <tr>
301 <td class="name" nowrap><a href="#cidr.equal">cidr:equal</a>&nbsp;(addr)</td>
302 <td class="summary">
303
304 Checks whether this CIDR instance is equal to the given argument.</td>
305 </tr>
306
307 <tr>
308 <td class="name" nowrap><a href="#cidr.prefix">cidr:prefix</a>&nbsp;(mask)</td>
309 <td class="summary">
310
311 Get or set prefix size of CIDR instance.</td>
312 </tr>
313
314 <tr>
315 <td class="name" nowrap><a href="#cidr.network">cidr:network</a>&nbsp;(mask)</td>
316 <td class="summary">
317
318 Derive network address of CIDR instance.</td>
319 </tr>
320
321 <tr>
322 <td class="name" nowrap><a href="#cidr.host">cidr:host</a>&nbsp;()</td>
323 <td class="summary">
324
325 Derive host address of CIDR instance.</td>
326 </tr>
327
328 <tr>
329 <td class="name" nowrap><a href="#cidr.mask">cidr:mask</a>&nbsp;(mask)</td>
330 <td class="summary">
331
332 Derive netmask of CIDR instance.</td>
333 </tr>
334
335 <tr>
336 <td class="name" nowrap><a href="#cidr.broadcast">cidr:broadcast</a>&nbsp;(mask)</td>
337 <td class="summary">
338
339 Derive broadcast address of CIDR instance.</td>
340 </tr>
341
342 <tr>
343 <td class="name" nowrap><a href="#cidr.mapped4">cidr:mapped4</a>&nbsp;()</td>
344 <td class="summary">
345
346 Derive mapped IPv4 address of CIDR instance.</td>
347 </tr>
348
349 <tr>
350 <td class="name" nowrap><a href="#cidr.tomac">cidr:tomac</a>&nbsp;()</td>
351 <td class="summary">
352
353 Derive MAC address of IPv6 link local CIDR instance.</td>
354 </tr>
355
356 <tr>
357 <td class="name" nowrap><a href="#cidr.tolinklocal">cidr:tolinklocal</a>&nbsp;()</td>
358 <td class="summary">
359
360 Derive IPv6 link local address from MAC address CIDR instance.</td>
361 </tr>
362
363 <tr>
364 <td class="name" nowrap><a href="#cidr.contains">cidr:contains</a>&nbsp;(addr)</td>
365 <td class="summary">
366
367 Test whether CIDR contains given range.</td>
368 </tr>
369
370 <tr>
371 <td class="name" nowrap><a href="#cidr.add">cidr:add</a>&nbsp;(amount, inplace)</td>
372 <td class="summary">
373
374 Add given amount to CIDR instance.</td>
375 </tr>
376
377 <tr>
378 <td class="name" nowrap><a href="#cidr.sub">cidr:sub</a>&nbsp;(amount, inplace)</td>
379 <td class="summary">
380
381 Subtract given amount from CIDR instance.</td>
382 </tr>
383
384 <tr>
385 <td class="name" nowrap><a href="#cidr.minhost">cidr:minhost</a>&nbsp;()</td>
386 <td class="summary">
387
388 Calculate the lowest possible host address within this CIDR instance.</td>
389 </tr>
390
391 <tr>
392 <td class="name" nowrap><a href="#cidr.maxhost">cidr:maxhost</a>&nbsp;()</td>
393 <td class="summary">
394
395 Calculate the highest possible host address within this CIDR instance.</td>
396 </tr>
397
398 <tr>
399 <td class="name" nowrap><a href="#cidr.string">cidr:string</a>&nbsp;()</td>
400 <td class="summary">
401
402 Convert CIDR instance into string representation.</td>
403 </tr>
404
405 </table>
406
407
408
409
410
411
412 <br/>
413 <br/>
414
415
416 <h2><a name="functions"></a>Functions</h2>
417 <dl class="function">
418
419
420
421 <dt><a name="cidr.is4"></a><strong>cidr:is4</strong>&nbsp;()</dt>
422 <dd>
423
424
425 Checks whether the CIDR instance is an IPv4 address range
426
427
428
429
430
431
432
433
434 <h3>Return value:</h3>
435 <code>true</code> if the CIDR is an IPv4 range, else <code>false</code>
436
437
438
439 <h3>See also:</h3>
440 <ul>
441
442 <li><a href="#cidr.is6">
443 cidr:is6
444 </a>
445
446 <li><a href="#cidr.ismac">
447 cidr:ismac
448 </a>
449
450 </ul>
451
452 </dd>
453
454
455
456
457 <dt><a name="cidr.is4rfc1918"></a><strong>cidr:is4rfc1918</strong>&nbsp;()</dt>
458 <dd>
459
460
461 Checks whether the CIDR instance is within the private RFC1918 address space
462
463
464
465
466
467
468 <h3>Usage:</h3>
469 <pre>local addr = luci.ip.new("192.168.45.2/24")
470 if addr:is4rfc1918() then
471 print("Is a private address")
472 end</pre>
473
474
475
476 <h3>Return value:</h3>
477 <code>true</code> if the entire range of this CIDR lies within one of
478 the ranges <code>10.0.0.0-10.255.255.255</code>,
479 <code>172.16.0.0-172.31.0.0</code> or
480 <code>192.168.0.0-192.168.255.255</code>, else <code>false</code>.
481
482
483
484 </dd>
485
486
487
488
489 <dt><a name="cidr.is4linklocal"></a><strong>cidr:is4linklocal</strong>&nbsp;()</dt>
490 <dd>
491
492
493 Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address
494
495
496
497
498
499
500 <h3>Usage:</h3>
501 <pre>local addr = luci.ip.new("169.254.34.125")
502 if addr:is4linklocal() then
503 print("Is a zeroconf address")
504 end</pre>
505
506
507
508 <h3>Return value:</h3>
509 <code>true</code> if the entire range of this CIDR lies within the range
510 the range <code>169.254.0.0-169.254.255.255</code>, else <code>false</code>.
511
512
513
514 </dd>
515
516
517
518
519 <dt><a name="cidr.is6"></a><strong>cidr:is6</strong>&nbsp;()</dt>
520 <dd>
521
522
523 Checks whether the CIDR instance is an IPv6 address range
524
525
526
527
528
529
530
531
532 <h3>Return value:</h3>
533 <code>true</code> if the CIDR is an IPv6 range, else <code>false</code>
534
535
536
537 <h3>See also:</h3>
538 <ul>
539
540 <li><a href="#cidr.is4">
541 cidr:is4
542 </a>
543
544 <li><a href="#cidr.ismac">
545 cidr:ismac
546 </a>
547
548 </ul>
549
550 </dd>
551
552
553
554
555 <dt><a name="cidr.is6linklocal"></a><strong>cidr:is6linklocal</strong>&nbsp;()</dt>
556 <dd>
557
558
559 Checks whether the CIDR instance is an IPv6 link local address
560
561
562
563
564
565
566 <h3>Usage:</h3>
567 <pre>local addr = luci.ip.new("fe92:53a:3216:af01:221:63ff:fe75:aa17/64")
568 if addr:is6linklocal() then
569 print("Is a linklocal address")
570 end</pre>
571
572
573
574 <h3>Return value:</h3>
575 <code>true</code> if the entire range of this CIDR lies within the range
576 the <code>fe80::/10</code> range, else <code>false</code>.
577
578
579
580 </dd>
581
582
583
584
585 <dt><a name="cidr.is6mapped4"></a><strong>cidr:is6mapped4</strong>&nbsp;()</dt>
586 <dd>
587
588
589 Checks whether the CIDR instance is an IPv6 mapped IPv4 address
590
591
592
593
594
595
596 <h3>Usage:</h3>
597 <pre>local addr = luci.ip.new("::ffff:192.168.1.1")
598 if addr:is6mapped4() then
599 print("Is a mapped IPv4 address")
600 end</pre>
601
602
603
604 <h3>Return value:</h3>
605 <code>true</code> if the address is an IPv6 mapped IPv4 address in the
606 form <code>::ffff:1.2.3.4</code>.
607
608
609
610 </dd>
611
612
613
614
615 <dt><a name="cidr.ismac"></a><strong>cidr:ismac</strong>&nbsp;()</dt>
616 <dd>
617
618
619 Checks whether the CIDR instance is an ethernet MAC address range
620
621
622
623
624
625
626
627
628 <h3>Return value:</h3>
629 <code>true</code> if the CIDR is a MAC address range, else <code>false</code>
630
631
632
633 <h3>See also:</h3>
634 <ul>
635
636 <li><a href="#cidr.is4">
637 cidr:is4
638 </a>
639
640 <li><a href="#cidr.is6">
641 cidr:is6
642 </a>
643
644 </ul>
645
646 </dd>
647
648
649
650
651 <dt><a name="cidr.ismaclocal"></a><strong>cidr:ismaclocal</strong>&nbsp;()</dt>
652 <dd>
653
654
655 Checks whether the CIDR instance is a locally administered (LAA) MAC address
656
657
658
659
660
661
662 <h3>Usage:</h3>
663 <pre>local mac = luci.ip.new("02:C0:FF:EE:00:01")
664 if mac:ismaclocal() then
665 print("Is an LAA MAC address")
666 end</pre>
667
668
669
670 <h3>Return value:</h3>
671 <code>true</code> if the MAC address sets the locally administered bit.
672
673
674
675 </dd>
676
677
678
679
680 <dt><a name="cidr.ismacmcast"></a><strong>cidr:ismacmcast</strong>&nbsp;()</dt>
681 <dd>
682
683
684 Checks whether the CIDR instance is a multicast MAC address
685
686
687
688
689
690
691 <h3>Usage:</h3>
692 <pre>local mac = luci.ip.new("01:00:5E:7F:00:10")
693 if addr:ismacmcast() then
694 print("Is a multicast MAC address")
695 end</pre>
696
697
698
699 <h3>Return value:</h3>
700 <code>true</code> if the MAC address sets the multicast bit.
701
702
703
704 </dd>
705
706
707
708
709 <dt><a name="cidr.lower"></a><strong>cidr:lower</strong>&nbsp;(addr)</dt>
710 <dd>
711
712
713 Checks whether this CIDR instance is lower than the given argument.
714 The comparisation follows these rules:
715 <ul><li>An IPv4 address is always lower than an IPv6 address and IPv6 addresses
716 are considered lower than MAC addresses</li>
717 <li>Prefix sizes are ignored</li></ul>
718
719
720
721 <h3>Parameters</h3>
722 <ul>
723
724 <li>
725 addr: A <code>luci.ip.cidr</code> instance or a string convertible by
726 <code>luci.ip.new()</code> to compare against.
727 </li>
728
729 </ul>
730
731
732
733
734 <h3>Usage:</h3>
735 <pre>local addr = luci.ip.new("192.168.1.1")
736 print(addr:lower(addr)) -- false
737 print(addr:lower("10.10.10.10/24")) -- false
738 print(addr:lower(luci.ip.new("::1"))) -- true
739 print(addr:lower(luci.ip.new("192.168.200.1"))) -- true
740 print(addr:lower(luci.ip.new("00:14:22:01:23:45"))) -- true</pre>
741
742
743
744 <h3>Return value:</h3>
745 <code>true</code> if this CIDR is lower than the given address,
746 else <code>false</code>.
747
748
749
750 <h3>See also:</h3>
751 <ul>
752
753 <li><a href="#cidr.higher">
754 cidr:higher
755 </a>
756
757 <li><a href="#cidr.equal">
758 cidr:equal
759 </a>
760
761 </ul>
762
763 </dd>
764
765
766
767
768 <dt><a name="cidr.higher"></a><strong>cidr:higher</strong>&nbsp;(addr)</dt>
769 <dd>
770
771
772 Checks whether this CIDR instance is higher than the given argument.
773 The comparisation follows these rules:
774 <ul><li>An IPv4 address is always lower than an IPv6 address and IPv6 addresses
775 are considered lower than MAC addresses</li>
776 <li>Prefix sizes are ignored</li></ul>
777
778
779
780 <h3>Parameters</h3>
781 <ul>
782
783 <li>
784 addr: A <code>luci.ip.cidr</code> instance or a string convertible by
785 <code>luci.ip.new()</code> to compare against.
786 </li>
787
788 </ul>
789
790
791
792
793 <h3>Usage:</h3>
794 <pre>local addr = luci.ip.new("192.168.1.1")
795 print(addr:higher(addr)) -- false
796 print(addr:higher("10.10.10.10/24")) -- true
797 print(addr:higher(luci.ip.new("::1"))) -- false
798 print(addr:higher(luci.ip.new("192.168.200.1"))) -- false
799 print(addr:higher(luci.ip.new("00:14:22:01:23:45"))) -- false</pre>
800
801
802
803 <h3>Return value:</h3>
804 <code>true</code> if this CIDR is higher than the given address,
805 else <code>false</code>.
806
807
808
809 <h3>See also:</h3>
810 <ul>
811
812 <li><a href="#cidr.lower">
813 cidr:lower
814 </a>
815
816 <li><a href="#cidr.equal">
817 cidr:equal
818 </a>
819
820 </ul>
821
822 </dd>
823
824
825
826
827 <dt><a name="cidr.equal"></a><strong>cidr:equal</strong>&nbsp;(addr)</dt>
828 <dd>
829
830
831 Checks whether this CIDR instance is equal to the given argument.
832
833
834
835 <h3>Parameters</h3>
836 <ul>
837
838 <li>
839 addr: A <code>luci.ip.cidr</code> instance or a string convertible by
840 <code>luci.ip.new()</code> to compare against.
841 </li>
842
843 </ul>
844
845
846
847
848 <h3>Usage:</h3>
849 <pre>local addr = luci.ip.new("192.168.1.1")
850 print(addr:equal(addr)) -- true
851 print(addr:equal("192.168.1.1")) -- true
852 print(addr:equal(luci.ip.new("::1"))) -- false
853
854 local addr6 = luci.ip.new("::1")
855 print(addr6:equal("0:0:0:0:0:0:0:1/64")) -- true
856 print(addr6:equal(luci.ip.new("fe80::221:63ff:fe75:aa17"))) -- false
857
858 local mac = luci.ip.new("00:14:22:01:23:45")
859 print(mac:equal("0:14:22:1:23:45")) -- true
860 print(mac:equal(luci.ip.new("01:23:45:67:89:AB")) -- false</pre>
861
862
863
864 <h3>Return value:</h3>
865 <code>true</code> if this CIDR is equal to the given address,
866 else <code>false</code>.
867
868
869
870 <h3>See also:</h3>
871 <ul>
872
873 <li><a href="#cidr.lower">
874 cidr:lower
875 </a>
876
877 <li><a href="#cidr.higher">
878 cidr:higher
879 </a>
880
881 </ul>
882
883 </dd>
884
885
886
887
888 <dt><a name="cidr.prefix"></a><strong>cidr:prefix</strong>&nbsp;(mask)</dt>
889 <dd>
890
891
892 Get or set prefix size of CIDR instance.
893 If the optional mask parameter is given, the prefix size of this CIDR is altered
894 else the current prefix size is returned.
895
896
897
898 <h3>Parameters</h3>
899 <ul>
900
901 <li>
902 mask: Either a number containing the number of bits (<code>0..32</code>
903 for IPv4, <code>0..128</code> for IPv6 or <code>0..48</code> for MAC addresses) or a string
904 containing a valid netmask (optional)
905 </li>
906
907 </ul>
908
909
910
911
912 <h3>Usage:</h3>
913 <pre>local range = luci.ip.new("192.168.1.1/255.255.255.0")
914 print(range:prefix()) -- 24
915
916 range:prefix(16)
917 print(range:prefix()) -- 16
918
919 range:prefix("255.255.255.255")
920 print(range:prefix()) -- 32</pre>
921
922
923
924 <h3>Return value:</h3>
925 Bit count of the current prefix size
926
927
928
929 </dd>
930
931
932
933
934 <dt><a name="cidr.network"></a><strong>cidr:network</strong>&nbsp;(mask)</dt>
935 <dd>
936
937
938 Derive network address of CIDR instance.
939
940 Returns a new CIDR instance representing the network address of this instance
941 with all host parts masked out. The used prefix size can be overridden by the
942 optional mask parameter.
943
944
945
946 <h3>Parameters</h3>
947 <ul>
948
949 <li>
950 mask: Either a number containing the number of bits (<code>0..32</code>
951 for IPv4, <code>0..128</code> for IPv6 or <code>0..48</code> for MAC addresses) or a string
952 containing a valid netmask (optional)
953 </li>
954
955 </ul>
956
957
958
959
960 <h3>Usage:</h3>
961 <pre>local range = luci.ip.new("192.168.62.243/255.255.0.0")
962 print(range:network()) -- "192.168.0.0"
963 print(range:network(24)) -- "192.168.62.0"
964 print(range:network("255.255.255.0")) -- "192.168.62.0"
965
966 local range6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
967 print(range6:network()) -- "fd9b:62b3:9cc5::"</pre>
968
969
970
971 <h3>Return value:</h3>
972 CIDR instance representing the network address
973
974
975
976 </dd>
977
978
979
980
981 <dt><a name="cidr.host"></a><strong>cidr:host</strong>&nbsp;()</dt>
982 <dd>
983
984
985 Derive host address of CIDR instance.
986
987 This function essentially constructs a copy of this CIDR with the prefix size
988 set to <code>32</code> for IPv4, <code>128</code> for IPv6 or <code>48</code> for MAC addresses.
989
990
991
992
993
994
995 <h3>Usage:</h3>
996 <pre>local range = luci.ip.new("172.19.37.45/16")
997 print(range) -- "172.19.37.45/16"
998 print(range:host()) -- "172.19.37.45"</pre>
999
1000
1001
1002 <h3>Return value:</h3>
1003 CIDR instance representing the host address
1004
1005
1006
1007 </dd>
1008
1009
1010
1011
1012 <dt><a name="cidr.mask"></a><strong>cidr:mask</strong>&nbsp;(mask)</dt>
1013 <dd>
1014
1015
1016 Derive netmask of CIDR instance.
1017
1018 Constructs a CIDR instance representing the netmask of this instance. The used
1019 prefix size can be overridden by the optional mask parameter.
1020
1021
1022
1023 <h3>Parameters</h3>
1024 <ul>
1025
1026 <li>
1027 mask: Either a number containing the number of bits (<code>0..32</code>
1028 for IPv4, <code>0..128</code> for IPv6 or <code>0..48</code> for MAC addresses) or a string
1029 containing a valid netmask (optional)
1030 </li>
1031
1032 </ul>
1033
1034
1035
1036
1037 <h3>Usage:</h3>
1038 <pre>local range = luci.ip.new("172.19.37.45/16")
1039 print(range:mask()) -- "255.255.0.0"
1040 print(range:mask(24)) -- "255.255.255.0"
1041 print(range:mask("255.0.0.0")) -- "255.0.0.0"</pre>
1042
1043
1044
1045 <h3>Return value:</h3>
1046 CIDR instance representing the netmask
1047
1048
1049
1050 </dd>
1051
1052
1053
1054
1055 <dt><a name="cidr.broadcast"></a><strong>cidr:broadcast</strong>&nbsp;(mask)</dt>
1056 <dd>
1057
1058
1059 Derive broadcast address of CIDR instance.
1060
1061 Constructs a CIDR instance representing the broadcast address of this instance.
1062 The used prefix size can be overridden by the optional mask parameter.
1063
1064 This function has no effect on IPv6 or MAC address instances, it will return
1065 nothing in this case.
1066
1067
1068
1069 <h3>Parameters</h3>
1070 <ul>
1071
1072 <li>
1073 mask: Either a number containing the number of bits (<code>0..32</code> for IPv4) or
1074 a string containing a valid netmask (optional)
1075 </li>
1076
1077 </ul>
1078
1079
1080
1081
1082 <h3>Usage:</h3>
1083 <pre>local range = luci.ip.new("172.19.37.45/16")
1084 print(range:broadcast()) -- "172.19.255.255"
1085 print(range:broadcast(24)) -- "172.19.37.255"
1086 print(range:broadcast("255.0.0.0")) -- "172.255.255.255"</pre>
1087
1088
1089
1090 <h3>Return value:</h3>
1091 Return a new CIDR instance representing the broadcast address if this
1092 instance is an IPv4 range, else return nothing.
1093
1094
1095
1096 </dd>
1097
1098
1099
1100
1101 <dt><a name="cidr.mapped4"></a><strong>cidr:mapped4</strong>&nbsp;()</dt>
1102 <dd>
1103
1104
1105 Derive mapped IPv4 address of CIDR instance.
1106
1107 Constructs a CIDR instance representing the IPv4 address of the IPv6 mapped
1108 IPv4 address in this instance.
1109
1110 This function has no effect on IPv4 instances, MAC address instances or IPv6
1111 instances which are not a mapped address, it will return nothing in this case.
1112
1113
1114
1115
1116
1117
1118 <h3>Usage:</h3>
1119 <pre>local addr = luci.ip.new("::ffff:172.16.19.1")
1120 print(addr:mapped4()) -- "172.16.19.1"</pre>
1121
1122
1123
1124 <h3>Return value:</h3>
1125 Return a new CIDR instance representing the IPv4 address if this
1126 instance is an IPv6 mapped IPv4 address, else return nothing.
1127
1128
1129
1130 </dd>
1131
1132
1133
1134
1135 <dt><a name="cidr.tomac"></a><strong>cidr:tomac</strong>&nbsp;()</dt>
1136 <dd>
1137
1138
1139 Derive MAC address of IPv6 link local CIDR instance.
1140
1141 Constructs a CIDR instance representing the MAC address contained in the IPv6
1142 link local address of this instance.
1143
1144 This function has no effect on IPv4 instances, MAC address instances or IPv6
1145 instances which are not a link local address, it will return nothing in this
1146 case.
1147
1148
1149
1150
1151
1152
1153 <h3>Usage:</h3>
1154 <pre>local addr = luci.ip.new("fe80::6666:b3ff:fe47:e1b9")
1155 print(addr:tomac()) -- "64:66:B3:47:E1:B9"</pre>
1156
1157
1158
1159 <h3>Return value:</h3>
1160 Return a new CIDR instance representing the MAC address if this
1161 instance is an IPv6 link local address, else return nothing.
1162
1163
1164
1165 </dd>
1166
1167
1168
1169
1170 <dt><a name="cidr.tolinklocal"></a><strong>cidr:tolinklocal</strong>&nbsp;()</dt>
1171 <dd>
1172
1173
1174 Derive IPv6 link local address from MAC address CIDR instance.
1175
1176 Constructs a CIDR instance representing the IPv6 link local address of the
1177 MAC address represented by this instance.
1178
1179 This function has no effect on IPv4 instances or IPv6 instances, it will return
1180 nothing in this case.
1181
1182
1183
1184
1185
1186
1187 <h3>Usage:</h3>
1188 <pre>local mac = luci.ip.new("64:66:B3:47:E1:B9")
1189 print(mac:tolinklocal()) -- "fe80::6666:b3ff:fe47:e1b9"</pre>
1190
1191
1192
1193 <h3>Return value:</h3>
1194 Return a new CIDR instance representing the IPv6 link local address.
1195
1196
1197
1198 </dd>
1199
1200
1201
1202
1203 <dt><a name="cidr.contains"></a><strong>cidr:contains</strong>&nbsp;(addr)</dt>
1204 <dd>
1205
1206
1207 Test whether CIDR contains given range.
1208
1209
1210
1211 <h3>Parameters</h3>
1212 <ul>
1213
1214 <li>
1215 addr: A <code>luci.ip.cidr</code> instance or a string convertible by
1216 <code>luci.ip.new()</code> to test.
1217 </li>
1218
1219 </ul>
1220
1221
1222
1223
1224 <h3>Usage:</h3>
1225 <pre>local range = luci.ip.new("10.24.0.0/255.255.0.0")
1226 print(range:contains("10.24.5.1")) -- true
1227 print(range:contains("::1")) -- false
1228 print(range:contains("10.0.0.0/8")) -- false
1229
1230 local range6 = luci.ip.new("fe80::/10")
1231 print(range6:contains("fe80::221:63f:fe75:aa17/64")) -- true
1232 print(range6:contains("fd9b:6b3:c5:0:221:63f:fe75:aa17/64")) -- false
1233
1234 local intel_macs = luci.ip.MAC("C0:B6:F9:00:00:00/24")
1235 print(intel_macs:contains("C0:B6:F9:A3:C:11")) -- true
1236 print(intel_macs:contains("64:66:B3:47:E1:B9")) -- false</pre>
1237
1238
1239
1240 <h3>Return value:</h3>
1241 <code>true</code> if this instance fully contains the given address else
1242 <code>false</code>.
1243
1244
1245
1246 </dd>
1247
1248
1249
1250
1251 <dt><a name="cidr.add"></a><strong>cidr:add</strong>&nbsp;(amount, inplace)</dt>
1252 <dd>
1253
1254
1255 Add given amount to CIDR instance. If the result would overflow the maximum
1256 address space, the result is set to the highest possible address.
1257
1258
1259
1260 <h3>Parameters</h3>
1261 <ul>
1262
1263 <li>
1264 amount: A numeric value between 0 and 0xFFFFFFFF, a
1265 <code>luci.ip.cidr</code> instance or a string convertible by
1266 <code>luci.ip.new()</code>.
1267 </li>
1268
1269 <li>
1270 inplace: If <code>true</code>, modify this instance instead of returning
1271 a new derived CIDR instance.
1272 </li>
1273
1274 </ul>
1275
1276
1277
1278
1279 <h3>Usage:</h3>
1280 <pre>local addr = luci.ip.new("192.168.1.1/24")
1281 print(addr:add(250)) -- "192.168.1.251/24"
1282 print(addr:add("0.0.99.0")) -- "192.168.100.1/24"
1283
1284 addr:add(256, true) -- true
1285 print(addr) -- "192.168.2.1/24
1286
1287 addr:add("255.0.0.0", true) -- false (overflow)
1288 print(addr) -- "255.255.255.255/24
1289
1290 local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
1291 print(addr6:add(256)) -- "fe80::221:63f:fe75:ab17/64"
1292 print(addr6:add("::ffff:0")) -- "fe80::221:640:fe74:aa17/64"
1293
1294 addr6:add(256, true) -- true
1295 print(addr6) -- "fe80::221:63f:fe75:ab17/64
1296
1297 addr6:add("ffff::", true) -- false (overflow)
1298 print(addr6) -- "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/64"
1299
1300 local mac = luci.ip.new("00:14:22:01:23:45")
1301 print(mac:add(256)) -- "00:14:22:01:24:45"
1302 print(mac:add("0:0:0:0:FF:0") -- "00:14:22:02:22:45"
1303
1304 mac:add(256, true) -- true
1305 print(mac) -- "00:14:22:01:24:45"
1306
1307 mac:add("FF:FF:0:0:0:0", true) -- false (overflow)
1308 print(mac) -- "FF:FF:FF:FF:FF:FF"</pre>
1309
1310
1311
1312 <h3>Return value:</h3>
1313 <ul>
1314 <li>When adding inplace: Return <code>true</code> if the addition succeeded
1315 or <code>false</code> when the addition overflowed.</li>
1316 <li>When deriving new CIDR: Return new instance representing the value of
1317 this instance plus the added amount or the highest possible address if
1318 the addition overflowed the available address space.</li></ul>
1319
1320
1321
1322 </dd>
1323
1324
1325
1326
1327 <dt><a name="cidr.sub"></a><strong>cidr:sub</strong>&nbsp;(amount, inplace)</dt>
1328 <dd>
1329
1330
1331 Subtract given amount from CIDR instance. If the result would under, the lowest
1332 possible address is returned.
1333
1334
1335
1336 <h3>Parameters</h3>
1337 <ul>
1338
1339 <li>
1340 amount: A numeric value between 0 and 0xFFFFFFFF, a
1341 <code>luci.ip.cidr</code> instance or a string convertible by
1342 <code>luci.ip.new()</code>.
1343 </li>
1344
1345 <li>
1346 inplace: If <code>true</code>, modify this instance instead of returning
1347 a new derived CIDR instance.
1348 </li>
1349
1350 </ul>
1351
1352
1353
1354
1355 <h3>Usage:</h3>
1356 <pre>local addr = luci.ip.new("192.168.1.1/24")
1357 print(addr:sub(256)) -- "192.168.0.1/24"
1358 print(addr:sub("0.168.0.0")) -- "192.0.1.1/24"
1359
1360 addr:sub(256, true) -- true
1361 print(addr) -- "192.168.0.1/24
1362
1363 addr:sub("255.0.0.0", true) -- false (underflow)
1364 print(addr) -- "0.0.0.0/24
1365
1366 local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
1367 print(addr6:sub(256)) -- "fe80::221:63f:fe75:a917/64"
1368 print(addr6:sub("::ffff:0")) -- "fe80::221:63e:fe76:aa17/64"
1369
1370 addr:sub(256, true) -- true
1371 print(addr) -- "fe80::221:63f:fe75:a917/64"
1372
1373 addr:sub("ffff::", true) -- false (underflow)
1374 print(addr) -- "::/64"
1375
1376 local mac = luci.ip.new("00:14:22:01:23:45")
1377 print(mac:sub(256)) -- "00:14:22:01:22:45"
1378 print(mac:sub("0:0:0:0:FF:0") -- "00:14:22:00:24:45"
1379
1380 mac:sub(256, true) -- true
1381 print(mac) -- "00:14:22:01:22:45"
1382
1383 mac:sub("FF:FF:0:0:0:0", true) -- false (overflow)
1384 print(mac) -- "00:00:00:00:00:00"</pre>
1385
1386
1387
1388 <h3>Return value:</h3>
1389 <ul>
1390 <li>When subtracting inplace: Return <code>true</code> if the subtraction
1391 succeeded or <code>false</code> when the subtraction underflowed.</li>
1392 <li>When deriving new CIDR: Return new instance representing the value of
1393 this instance minus the subtracted amount or the lowest address if
1394 the subtraction underflowed.</li></ul>
1395
1396
1397
1398 </dd>
1399
1400
1401
1402
1403 <dt><a name="cidr.minhost"></a><strong>cidr:minhost</strong>&nbsp;()</dt>
1404 <dd>
1405
1406
1407 Calculate the lowest possible host address within this CIDR instance.
1408
1409
1410
1411
1412
1413
1414 <h3>Usage:</h3>
1415 <pre>local addr = luci.ip.new("192.168.123.56/24")
1416 print(addr:minhost()) -- "192.168.123.1"
1417
1418 local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
1419 print(addr6:minhost()) -- "fd9b:62b3:9cc5::1"
1420
1421 local mac = luci.ip.new("00:14:22:01:22:45/32")
1422 print(mac:minhost()) -- "00:14:22:01:00:01"</pre>
1423
1424
1425
1426 <h3>Return value:</h3>
1427 Returns a new CIDR instance representing the lowest host address
1428 within this range.
1429
1430
1431
1432 </dd>
1433
1434
1435
1436
1437 <dt><a name="cidr.maxhost"></a><strong>cidr:maxhost</strong>&nbsp;()</dt>
1438 <dd>
1439
1440
1441 Calculate the highest possible host address within this CIDR instance.
1442
1443
1444
1445
1446
1447
1448 <h3>Usage:</h3>
1449 <pre>local addr = luci.ip.new("192.168.123.56/24")
1450 print(addr:maxhost()) -- "192.168.123.254" (.255 is broadcast)
1451
1452 local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
1453 print(addr6:maxhost()) -- "fd9b:62b3:9cc5:0:ffff:ffff:ffff:ffff"
1454
1455 local mac = luci.ip.new("00:14:22:01:22:45/32")
1456 print(mac:maxhost()) -- "00:14:22:01:FF:FF"</pre>
1457
1458
1459
1460 <h3>Return value:</h3>
1461 Returns a new CIDR instance representing the highest host address
1462 within this range.
1463
1464
1465
1466 </dd>
1467
1468
1469
1470
1471 <dt><a name="cidr.string"></a><strong>cidr:string</strong>&nbsp;()</dt>
1472 <dd>
1473
1474
1475 Convert CIDR instance into string representation.
1476
1477 If the prefix size of instance is less than 32 for IPv4, 128 for IPv6 or 48 for
1478 MACs, the address is returned in the form "address/prefix" otherwise just
1479 "address".
1480
1481 It is usually not required to call this function directly as CIDR objects
1482 define it as __tostring function in the associated metatable.
1483
1484
1485
1486
1487
1488
1489
1490
1491 <h3>Return value:</h3>
1492 Returns a string representing the range or address of this CIDR instance
1493
1494
1495
1496 </dd>
1497
1498
1499 </dl>
1500
1501
1502
1503
1504
1505 </div> <!-- id="content" -->
1506
1507 </div> <!-- id="main" -->
1508
1509 <div id="about">
1510 <p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
1511 </div> <!-- id="about" -->
1512
1513 </div> <!-- id="container" -->
1514 </body>
1515 </html>