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