doc/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.protocol.html">luci.http.protocol</a>
  43         </li>
  44
  45         <li>
  46                 <a href="../modules/luci.http.protocol.conditionals.html">luci.http.protocol.conditionals</a>
  47         </li>
  48
  49         <li>
  50                 <a href="../modules/luci.http.protocol.date.html">luci.http.protocol.date</a>
  51         </li>
  52
  53         <li>
  54                 <a href="../modules/luci.http.protocol.mime.html">luci.http.protocol.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.jsonc.html">luci.jsonc</a>
  69         </li>
  70
  71         <li>
  72                 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
  73         </li>
  74
  75         <li>
  76                 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
  77         </li>
  78
  79         <li>
  80                 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
  81         </li>
  82
  83         <li>
  84                 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
  85         </li>
  86
  87         <li>
  88                 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
  89         </li>
  90
  91         <li>
  92                 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
  93         </li>
  94
  95         <li>
  96                 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
  97         </li>
  98
  99         <li>
 100                 <a href="../modules/nixio.html">nixio</a>
 101         </li>
 102
 103         <li>
 104                 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
 105         </li>
 106
 107         <li>
 108                 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
 109         </li>
 110
 111         <li>
 112                 <a href="../modules/nixio.File.html">nixio.File</a>
 113         </li>
 114
 115         <li>
 116                 <a href="../modules/nixio.README.html">nixio.README</a>
 117         </li>
 118
 119         <li>
 120                 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
 121         </li>
 122
 123         <li>
 124                 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
 125         </li>
 126
 127         <li>
 128                 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
 129         </li>
 130
 131         <li>
 132                 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
 133         </li>
 134
 135         <li>
 136                 <a href="../modules/nixio.bin.html">nixio.bin</a>
 137         </li>
 138
 139         <li>
 140                 <a href="../modules/nixio.bit.html">nixio.bit</a>
 141         </li>
 142
 143         <li>
 144                 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
 145         </li>
 146
 147         <li>
 148                 <a href="../modules/nixio.fs.html">nixio.fs</a>
 149         </li>
 150
 151 </ul>
 152
 153
 154
 155 <!-- File list -->
 156
 157
 158
 159
 160
 161
 162
 163 </div><!-- id="navigation" -->
 164
 165 <div id="content">
 166
 167 <h1>Object Instance <code>luci.ip.cidr</code></h1>
 168
 169 <p>
 170  IP CIDR Object.
 171  Represents an IPv4 or IPv6 address range.</p>
 172
 173
 174
 175
 176
 177
 178
 179 <h2>Functions</h2>
 180 <table class="function_list">
 181
 182         <tr>
 183         <td class="name" nowrap><a href="#cidr.is4">cidr:is4</a>&nbsp;()</td>
 184         <td class="summary">
 185
 186 Checks whether the CIDR instance is an IPv4 address range
 187  </td>
 188         </tr>
 189
 190         <tr>
 191         <td class="name" nowrap><a href="#cidr.is4rfc1918">cidr:is4rfc1918</a>&nbsp;()</td>
 192         <td class="summary">
 193
 194 Checks whether the CIDR instance is within the private RFC1918 address space
 195  </td>
 196         </tr>
 197
 198         <tr>
 199         <td class="name" nowrap><a href="#cidr.is4linklocal">cidr:is4linklocal</a>&nbsp;()</td>
 200         <td class="summary">
 201
 202 Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address
 203  </td>
 204         </tr>
 205
 206         <tr>
 207         <td class="name" nowrap><a href="#cidr.is6">cidr:is6</a>&nbsp;()</td>
 208         <td class="summary">
 209
 210 Checks whether the CIDR instance is an IPv6 address range
 211  </td>
 212         </tr>
 213
 214         <tr>
 215         <td class="name" nowrap><a href="#cidr.is6linklocal">cidr:is6linklocal</a>&nbsp;()</td>
 216         <td class="summary">
 217
 218 Checks whether the CIDR instance is an IPv6 link local address
 219  </td>
 220         </tr>
 221
 222         <tr>
 223         <td class="name" nowrap><a href="#cidr.is6mapped4">cidr:is6mapped4</a>&nbsp;()</td>
 224         <td class="summary">
 225
 226 Checks whether the CIDR instance is an IPv6 mapped IPv4 address
 227  </td>
 228         </tr>
 229
 230         <tr>
 231         <td class="name" nowrap><a href="#cidr.lower">cidr:lower</a>&nbsp;(addr)</td>
 232         <td class="summary">
 233
 234 Checks whether this CIDR instance is lower than the given argument.</td>
 235         </tr>
 236
 237         <tr>
 238         <td class="name" nowrap><a href="#cidr.higher">cidr:higher</a>&nbsp;(addr)</td>
 239         <td class="summary">
 240
 241 Checks whether this CIDR instance is higher than the given argument.</td>
 242         </tr>
 243
 244         <tr>
 245         <td class="name" nowrap><a href="#cidr.equal">cidr:equal</a>&nbsp;(addr)</td>
 246         <td class="summary">
 247
 248 Checks whether this CIDR instance is equal to the given argument.</td>
 249         </tr>
 250
 251         <tr>
 252         <td class="name" nowrap><a href="#cidr.prefix">cidr:prefix</a>&nbsp;(mask)</td>
 253         <td class="summary">
 254
 255 Get or set prefix size of CIDR instance.</td>
 256         </tr>
 257
 258         <tr>
 259         <td class="name" nowrap><a href="#cidr.network">cidr:network</a>&nbsp;(mask)</td>
 260         <td class="summary">
 261
 262 Derive network address of CIDR instance.</td>
 263         </tr>
 264
 265         <tr>
 266         <td class="name" nowrap><a href="#cidr.host">cidr:host</a>&nbsp;()</td>
 267         <td class="summary">
 268
 269 Derive host address of CIDR instance.</td>
 270         </tr>
 271
 272         <tr>
 273         <td class="name" nowrap><a href="#cidr.mask">cidr:mask</a>&nbsp;(mask)</td>
 274         <td class="summary">
 275
 276 Derive netmask of CIDR instance.</td>
 277         </tr>
 278
 279         <tr>
 280         <td class="name" nowrap><a href="#cidr.broadcast">cidr:broadcast</a>&nbsp;(mask)</td>
 281         <td class="summary">
 282
 283 Derive broadcast address of CIDR instance.</td>
 284         </tr>
 285
 286         <tr>
 287         <td class="name" nowrap><a href="#cidr.mapped4">cidr:mapped4</a>&nbsp;()</td>
 288         <td class="summary">
 289
 290 Derive mapped IPv4 address of CIDR instance.</td>
 291         </tr>
 292
 293         <tr>
 294         <td class="name" nowrap><a href="#cidr.contains">cidr:contains</a>&nbsp;(addr)</td>
 295         <td class="summary">
 296
 297 Test whether CIDR contains given range.</td>
 298         </tr>
 299
 300         <tr>
 301         <td class="name" nowrap><a href="#cidr.add">cidr:add</a>&nbsp;(amount, inplace)</td>
 302         <td class="summary">
 303
 304 Add given amount to CIDR instance.</td>
 305         </tr>
 306
 307         <tr>
 308         <td class="name" nowrap><a href="#cidr.sub">cidr:sub</a>&nbsp;(amount, inplace)</td>
 309         <td class="summary">
 310
 311 Substract given amount from CIDR instance.</td>
 312         </tr>
 313
 314         <tr>
 315         <td class="name" nowrap><a href="#cidr.minhost">cidr:minhost</a>&nbsp;()</td>
 316         <td class="summary">
 317
 318 Calculate the lowest possible host address within this CIDR instance.</td>
 319         </tr>
 320
 321         <tr>
 322         <td class="name" nowrap><a href="#cidr.maxhost">cidr:maxhost</a>&nbsp;()</td>
 323         <td class="summary">
 324
 325 Calculate the highest possible host address within this CIDR instance.</td>
 326         </tr>
 327
 328         <tr>
 329         <td class="name" nowrap><a href="#cidr.string">cidr:string</a>&nbsp;()</td>
 330         <td class="summary">
 331
 332 Convert CIDR instance into string representation.</td>
 333         </tr>
 334
 335 </table>
 336
 337
 338
 339
 340
 341
 342 <br/>
 343 <br/>
 344
 345
 346 <h2><a name="functions"></a>Functions</h2>
 347 <dl class="function">
 348
 349
 350
 351 <dt><a name="cidr.is4"></a><strong>cidr:is4</strong>&nbsp;()</dt>
 352 <dd>
 353
 354
 355 Checks whether the CIDR instance is an IPv4 address range
 356
 357
 358
 359
 360
 361
 362
 363
 364 <h3>Return value:</h3>
 365 <code>true</code> if the CIDR is an IPv4 range, else <code>false</code>
 366
 367
 368
 369 <h3>See also:</h3>
 370 <ul>
 371
 372         <li><a href="#cidr.is6">
 373                 cidr:is6
 374         </a>
 375
 376 </ul>
 377
 378 </dd>
 379
 380
 381
 382
 383 <dt><a name="cidr.is4rfc1918"></a><strong>cidr:is4rfc1918</strong>&nbsp;()</dt>
 384 <dd>
 385
 386
 387 Checks whether the CIDR instance is within the private RFC1918 address space
 388
 389
 390
 391
 392
 393
 394 <h3>Usage:</h3>
 395 <pre>local addr = luci.ip.new("192.168.45.2/24")
 396 if addr:is4rfc1918() then
 397         print("Is a private address")
 398 end</pre>
 399
 400
 401
 402 <h3>Return value:</h3>
 403 <code>true</code> if the entire range of this CIDR lies within one of
 404         the ranges <code>10.0.0.0-10.255.255.255</code>,
 405         <code>172.16.0.0-172.31.0.0</code> or
 406         <code>192.168.0.0-192.168.255.255</code>, else <code>false</code>.
 407
 408
 409
 410 </dd>
 411
 412
 413
 414
 415 <dt><a name="cidr.is4linklocal"></a><strong>cidr:is4linklocal</strong>&nbsp;()</dt>
 416 <dd>
 417
 418
 419 Checks whether the CIDR instance is an IPv4 link local (Zeroconf) address
 420
 421
 422
 423
 424
 425
 426 <h3>Usage:</h3>
 427 <pre>local addr = luci.ip.new("169.254.34.125")
 428 if addr:is4linklocal() then
 429         print("Is a zeroconf address")
 430 end</pre>
 431
 432
 433
 434 <h3>Return value:</h3>
 435 <code>true</code> if the entire range of this CIDR lies within the range
 436         the range <code>169.254.0.0-169.254.255.255</code>, else <code>false</code>.
 437
 438
 439
 440 </dd>
 441
 442
 443
 444
 445 <dt><a name="cidr.is6"></a><strong>cidr:is6</strong>&nbsp;()</dt>
 446 <dd>
 447
 448
 449 Checks whether the CIDR instance is an IPv6 address range
 450
 451
 452
 453
 454
 455
 456
 457
 458 <h3>Return value:</h3>
 459 <code>true</code> if the CIDR is an IPv6 range, else <code>false</code>
 460
 461
 462
 463 <h3>See also:</h3>
 464 <ul>
 465
 466         <li><a href="#cidr.is4">
 467                 cidr:is4
 468         </a>
 469
 470 </ul>
 471
 472 </dd>
 473
 474
 475
 476
 477 <dt><a name="cidr.is6linklocal"></a><strong>cidr:is6linklocal</strong>&nbsp;()</dt>
 478 <dd>
 479
 480
 481 Checks whether the CIDR instance is an IPv6 link local address
 482
 483
 484
 485
 486
 487
 488 <h3>Usage:</h3>
 489 <pre>local addr = luci.ip.new("fe92:53a:3216:af01:221:63ff:fe75:aa17/64")
 490 if addr:is6linklocal() then
 491         print("Is a linklocal address")
 492 end</pre>
 493
 494
 495
 496 <h3>Return value:</h3>
 497 <code>true</code> if the entire range of this CIDR lies within the range
 498         the <code>fe80::/10</code> range, else <code>false</code>.
 499
 500
 501
 502 </dd>
 503
 504
 505
 506
 507 <dt><a name="cidr.is6mapped4"></a><strong>cidr:is6mapped4</strong>&nbsp;()</dt>
 508 <dd>
 509
 510
 511 Checks whether the CIDR instance is an IPv6 mapped IPv4 address
 512
 513
 514
 515
 516
 517
 518 <h3>Usage:</h3>
 519 <pre>local addr = luci.ip.new("::ffff:192.168.1.1")
 520 if addr:is6mapped4() then
 521         print("Is a mapped IPv4 address")
 522 end</pre>
 523
 524
 525
 526 <h3>Return value:</h3>
 527 <code>true</code> if the address is an IPv6 mapped IPv4 address in the
 528         form <code>::ffff:1.2.3.4</code>.
 529
 530
 531
 532 </dd>
 533
 534
 535
 536
 537 <dt><a name="cidr.lower"></a><strong>cidr:lower</strong>&nbsp;(addr)</dt>
 538 <dd>
 539
 540
 541 Checks whether this CIDR instance is lower than the given argument.
 542 The comparisation follows these rules:
 543 <ul><li>An IPv4 address is always lower than an IPv6 address</li>
 544 <li>Prefix sizes are ignored</li></ul>
 545
 546
 547
 548 <h3>Parameters</h3>
 549 <ul>
 550
 551         <li>
 552           addr: A <code>luci.ip.cidr</code> instance or a string convertable by
 553         <code>luci.ip.new()</code> to compare against.
 554         </li>
 555
 556 </ul>
 557
 558
 559
 560
 561 <h3>Usage:</h3>
 562 <pre>local addr = luci.ip.new("192.168.1.1")
 563 print(addr:lower(addr)) -- false
 564 print(addr:lower("10.10.10.10/24")) -- false
 565 print(addr:lower(luci.ip.new("::1"))) -- true
 566 print(addr:lower(luci.ip.new("192.168.200.1"))) -- true</pre>
 567
 568
 569
 570 <h3>Return value:</h3>
 571 <code>true</code> if this CIDR is lower than the given address,
 572         else <code>false</code>.
 573
 574
 575
 576 <h3>See also:</h3>
 577 <ul>
 578
 579         <li><a href="#cidr.higher">
 580                 cidr:higher
 581         </a>
 582
 583         <li><a href="#cidr.equal">
 584                 cidr:equal
 585         </a>
 586
 587 </ul>
 588
 589 </dd>
 590
 591
 592
 593
 594 <dt><a name="cidr.higher"></a><strong>cidr:higher</strong>&nbsp;(addr)</dt>
 595 <dd>
 596
 597
 598 Checks whether this CIDR instance is higher than the given argument.
 599 The comparisation follows these rules:
 600 <ul><li>An IPv4 address is always lower than an IPv6 address</li>
 601 <li>Prefix sizes are ignored</li></ul>
 602
 603
 604
 605 <h3>Parameters</h3>
 606 <ul>
 607
 608         <li>
 609           addr: A <code>luci.ip.cidr</code> instance or a string convertable by
 610         <code>luci.ip.new()</code> to compare against.
 611         </li>
 612
 613 </ul>
 614
 615
 616
 617
 618 <h3>Usage:</h3>
 619 <pre>local addr = luci.ip.new("192.168.1.1")
 620 print(addr:higher(addr)) -- false
 621 print(addr:higher("10.10.10.10/24")) -- true
 622 print(addr:higher(luci.ip.new("::1"))) -- false
 623 print(addr:higher(luci.ip.new("192.168.200.1"))) -- false</pre>
 624
 625
 626
 627 <h3>Return value:</h3>
 628 <code>true</code> if this CIDR is higher than the given address,
 629         else <code>false</code>.
 630
 631
 632
 633 <h3>See also:</h3>
 634 <ul>
 635
 636         <li><a href="#cidr.lower">
 637                 cidr:lower
 638         </a>
 639
 640         <li><a href="#cidr.equal">
 641                 cidr:equal
 642         </a>
 643
 644 </ul>
 645
 646 </dd>
 647
 648
 649
 650
 651 <dt><a name="cidr.equal"></a><strong>cidr:equal</strong>&nbsp;(addr)</dt>
 652 <dd>
 653
 654
 655 Checks whether this CIDR instance is equal to the given argument.
 656
 657
 658
 659 <h3>Parameters</h3>
 660 <ul>
 661
 662         <li>
 663           addr: A <code>luci.ip.cidr</code> instance or a string convertable by
 664         <code>luci.ip.new()</code> to compare against.
 665         </li>
 666
 667 </ul>
 668
 669
 670
 671
 672 <h3>Usage:</h3>
 673 <pre>local addr = luci.ip.new("192.168.1.1")
 674 print(addr:equal(addr)) -- true
 675 print(addr:equal("192.168.1.1")) -- true
 676 print(addr:equal(luci.ip.new("::1"))) -- false
 677
 678 local addr6 = luci.ip.new("::1")
 679 print(addr6:equal("0:0:0:0:0:0:0:1/64")) -- true
 680 print(addr6:equal(luci.ip.new("fe80::221:63ff:fe75:aa17"))) -- false</pre>
 681
 682
 683
 684 <h3>Return value:</h3>
 685 <code>true</code> if this CIDR is equal to the given address,
 686         else <code>false</code>.
 687
 688
 689
 690 <h3>See also:</h3>
 691 <ul>
 692
 693         <li><a href="#cidr.lower">
 694                 cidr:lower
 695         </a>
 696
 697         <li><a href="#cidr.higher">
 698                 cidr:higher
 699         </a>
 700
 701 </ul>
 702
 703 </dd>
 704
 705
 706
 707
 708 <dt><a name="cidr.prefix"></a><strong>cidr:prefix</strong>&nbsp;(mask)</dt>
 709 <dd>
 710
 711
 712 Get or set prefix size of CIDR instance.
 713 If the optional mask parameter is given, the prefix size of this CIDR is altered
 714 else the current prefix size is returned.
 715
 716
 717
 718 <h3>Parameters</h3>
 719 <ul>
 720
 721         <li>
 722           mask: Either a number containing the number of bits (<code>0..32</code>
 723         for IPv4, <code>0..128</code> for IPv6) or a string containing a valid
 724         netmask (optional)
 725         </li>
 726
 727 </ul>
 728
 729
 730
 731
 732 <h3>Usage:</h3>
 733 <pre>local range = luci.ip.new("192.168.1.1/255.255.255.0")
 734 print(range:prefix()) -- 24
 735
 736 range:prefix(16)
 737 print(range:prefix()) -- 16
 738
 739 range:prefix("255.255.255.255")
 740 print(range:prefix()) -- 32</pre>
 741
 742
 743
 744 <h3>Return value:</h3>
 745 Bit count of the current prefix size
 746
 747
 748
 749 </dd>
 750
 751
 752
 753
 754 <dt><a name="cidr.network"></a><strong>cidr:network</strong>&nbsp;(mask)</dt>
 755 <dd>
 756
 757
 758 Derive network address of CIDR instance.
 759
 760 Returns a new CIDR instance representing the network address of this instance
 761 with all host parts masked out. The used prefix size can be overridden by the
 762 optional mask parameter.
 763
 764
 765
 766 <h3>Parameters</h3>
 767 <ul>
 768
 769         <li>
 770           mask: Either a number containing the number of bits (<code>0..32</code>
 771         for IPv4, <code>0..128</code> for IPv6) or a string containing a valid
 772         netmask (optional)
 773         </li>
 774
 775 </ul>
 776
 777
 778
 779
 780 <h3>Usage:</h3>
 781 <pre>local range = luci.ip.new("192.168.62.243/255.255.0.0")
 782 print(range:network())                -- "192.168.0.0"
 783 print(range:network(24))              -- "192.168.62.0"
 784 print(range:network("255.255.255.0")) -- "192.168.62.0"
 785
 786 local range6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
 787 print(range6:network())               -- "fd9b:62b3:9cc5::"</pre>
 788
 789
 790
 791 <h3>Return value:</h3>
 792 CIDR instance representing the network address
 793
 794
 795
 796 </dd>
 797
 798
 799
 800
 801 <dt><a name="cidr.host"></a><strong>cidr:host</strong>&nbsp;()</dt>
 802 <dd>
 803
 804
 805 Derive host address of CIDR instance.
 806
 807 This function essentially constructs a copy of this CIDR with the prefix size
 808 set to <code>32</code> for IPv4 and <code>128</code> for IPv6.
 809
 810
 811
 812
 813
 814
 815 <h3>Usage:</h3>
 816 <pre>local range = luci.ip.new("172.19.37.45/16")
 817 print(range)        -- "172.19.37.45/16"
 818 print(range:host()) -- "172.19.37.45"</pre>
 819
 820
 821
 822 <h3>Return value:</h3>
 823 CIDR instance representing the host address
 824
 825
 826
 827 </dd>
 828
 829
 830
 831
 832 <dt><a name="cidr.mask"></a><strong>cidr:mask</strong>&nbsp;(mask)</dt>
 833 <dd>
 834
 835
 836 Derive netmask of CIDR instance.
 837
 838 Constructs a CIDR instance representing the netmask of this instance. The used
 839 prefix size can be overridden by the optional mask parameter.
 840
 841
 842
 843 <h3>Parameters</h3>
 844 <ul>
 845
 846         <li>
 847           mask: Either a number containing the number of bits (<code>0..32</code>
 848         for IPv4, <code>0..128</code> for IPv6) or a string containing a valid
 849         netmask (optional)
 850         </li>
 851
 852 </ul>
 853
 854
 855
 856
 857 <h3>Usage:</h3>
 858 <pre>local range = luci.ip.new("172.19.37.45/16")
 859 print(range:mask())            -- "255.255.0.0"
 860 print(range:mask(24))          -- "255.255.255.0"
 861 print(range:mask("255.0.0.0")) -- "255.0.0.0"</pre>
 862
 863
 864
 865 <h3>Return value:</h3>
 866 CIDR instance representing the netmask
 867
 868
 869
 870 </dd>
 871
 872
 873
 874
 875 <dt><a name="cidr.broadcast"></a><strong>cidr:broadcast</strong>&nbsp;(mask)</dt>
 876 <dd>
 877
 878
 879 Derive broadcast address of CIDR instance.
 880
 881 Constructs a CIDR instance representing the broadcast address of this instance.
 882 The used prefix size can be overridden by the optional mask parameter.
 883
 884 This function has no effect on IPv6 instances, it will return nothing in this
 885 case.
 886
 887
 888
 889 <h3>Parameters</h3>
 890 <ul>
 891
 892         <li>
 893           mask: Either a number containing the number of bits (<code>0..32</code>
 894         for IPv4, <code>0..128</code> for IPv6) or a string containing a valid
 895         netmask (optional)
 896         </li>
 897
 898 </ul>
 899
 900
 901
 902
 903 <h3>Usage:</h3>
 904 <pre>local range = luci.ip.new("172.19.37.45/16")
 905 print(range:broadcast())            -- "172.19.255.255"
 906 print(range:broadcast(24))          -- "172.19.37.255"
 907 print(range:broadcast("255.0.0.0")) -- "172.255.255.255"</pre>
 908
 909
 910
 911 <h3>Return value:</h3>
 912 Return a new CIDR instance representing the broadcast address if this
 913         instance is an IPv4 range, else return nothing.
 914
 915
 916
 917 </dd>
 918
 919
 920
 921
 922 <dt><a name="cidr.mapped4"></a><strong>cidr:mapped4</strong>&nbsp;()</dt>
 923 <dd>
 924
 925
 926 Derive mapped IPv4 address of CIDR instance.
 927
 928 Constructs a CIDR instance representing the IPv4 address of the IPv6 mapped
 929 IPv4 address in this instance.
 930
 931 This function has no effect on IPv4 instances or IPv6 instances which are not a
 932 mapped address, it will return nothing in this case.
 933
 934
 935
 936
 937
 938
 939 <h3>Usage:</h3>
 940 <pre>local addr = luci.ip.new("::ffff:172.16.19.1")
 941 print(addr:mapped4()) -- "172.16.19.1"</pre>
 942
 943
 944
 945 <h3>Return value:</h3>
 946 Return a new CIDR instance representing the IPv4 address if this
 947         instance is an IPv6 mapped IPv4 address, else return nothing.
 948
 949
 950
 951 </dd>
 952
 953
 954
 955
 956 <dt><a name="cidr.contains"></a><strong>cidr:contains</strong>&nbsp;(addr)</dt>
 957 <dd>
 958
 959
 960 Test whether CIDR contains given range.
 961
 962
 963
 964 <h3>Parameters</h3>
 965 <ul>
 966
 967         <li>
 968           addr: A <code>luci.ip.cidr</code> instance or a string convertable by
 969         <code>luci.ip.new()</code> to test.
 970         </li>
 971
 972 </ul>
 973
 974
 975
 976
 977 <h3>Usage:</h3>
 978 <pre>local range = luci.ip.new("10.24.0.0/255.255.0.0")
 979 print(range:contains("10.24.5.1"))  -- true
 980 print(range:contains("::1"))        -- false
 981 print(range:contains("10.0.0.0/8")) -- false
 982
 983 local range6 = luci.ip.new("fe80::/10")
 984 print(range6:contains("fe80::221:63f:fe75:aa17/64"))         -- true
 985 print(range6:contains("fd9b:6b3:c5:0:221:63f:fe75:aa17/64")) -- false</pre>
 986
 987
 988
 989 <h3>Return value:</h3>
 990 <code>true</code> if this instance fully contains the given address else
 991         <code>false</code>.
 992
 993
 994
 995 </dd>
 996
 997
 998
 999
1000 <dt><a name="cidr.add"></a><strong>cidr:add</strong>&nbsp;(amount, inplace)</dt>
1001 <dd>
1002
1003
1004 Add given amount to CIDR instance. If the result would overflow the maximum
1005 address space, the result is set to the highest possible address.
1006
1007
1008
1009 <h3>Parameters</h3>
1010 <ul>
1011
1012         <li>
1013           amount: A numeric value between 0 and 0xFFFFFFFF, a
1014         <code>luci.ip.cidr</code> instance or a string convertable by
1015         <code>luci.ip.new()</code>.
1016         </li>
1017
1018         <li>
1019           inplace: If <code>true</code>, modify this instance instead of returning
1020         a new derived CIDR instance.
1021         </li>
1022
1023 </ul>
1024
1025
1026
1027
1028 <h3>Usage:</h3>
1029 <pre>local addr = luci.ip.new("192.168.1.1/24")
1030 print(addr:add(250))         -- "192.168.1.251/24"
1031 print(addr:add("0.0.99.0"))  -- "192.168.100.1/24"
1032
1033 addr:add(256, true)          -- true
1034 print(addr)                  -- "192.168.2.1/24
1035
1036 addr:add("255.0.0.0", true)  -- false (overflow)
1037 print(addr)                  -- "255.255.255.255/24
1038
1039 local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
1040 print(addr6:add(256))        -- "fe80::221:63f:fe75:ab17/64"
1041 print(addr6:add("::ffff:0")) -- "fe80::221:640:fe74:aa17/64"
1042
1043 addr:add(256, true)          -- true
1044 print(addr)                  -- "fe80::221:63f:fe75:ab17/64
1045
1046 addr:add("ffff::", true)     -- false (overflow)
1047 print(addr)                  -- "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff/64"</pre>
1048
1049
1050
1051 <h3>Return value:</h3>
1052 <ul>
1053         <li>When adding inplace: Return <code>true</code> if the addition succeded
1054             or <code>false</code> when the addition overflowed.</li>
1055         <li>When deriving new CIDR: Return new instance representing the value of
1056         this instance plus the added amount or the highest possible address if
1057             the addition overflowed the available address space.</li></ul>
1058
1059
1060
1061 </dd>
1062
1063
1064
1065
1066 <dt><a name="cidr.sub"></a><strong>cidr:sub</strong>&nbsp;(amount, inplace)</dt>
1067 <dd>
1068
1069
1070 Substract given amount from CIDR instance. If the result would under, the lowest
1071 possible address is returned.
1072
1073
1074
1075 <h3>Parameters</h3>
1076 <ul>
1077
1078         <li>
1079           amount: A numeric value between 0 and 0xFFFFFFFF, a
1080         <code>luci.ip.cidr</code> instance or a string convertable by
1081         <code>luci.ip.new()</code>.
1082         </li>
1083
1084         <li>
1085           inplace: If <code>true</code>, modify this instance instead of returning
1086         a new derived CIDR instance.
1087         </li>
1088
1089 </ul>
1090
1091
1092
1093
1094 <h3>Usage:</h3>
1095 <pre>local addr = luci.ip.new("192.168.1.1/24")
1096 print(addr:sub(256))         -- "192.168.0.1/24"
1097 print(addr:sub("0.168.0.0")) -- "192.0.1.1/24"
1098
1099 addr:sub(256, true)          -- true
1100 print(addr)                  -- "192.168.0.1/24
1101
1102 addr:sub("255.0.0.0", true)  -- false (underflow)
1103 print(addr)                  -- "0.0.0.0/24
1104
1105 local addr6 = luci.ip.new("fe80::221:63f:fe75:aa17/64")
1106 print(addr6:sub(256))        -- "fe80::221:63f:fe75:a917/64"
1107 print(addr6:sub("::ffff:0")) -- "fe80::221:63e:fe76:aa17/64"
1108
1109 addr:sub(256, true)          -- true
1110 print(addr)                  -- "fe80::221:63f:fe75:a917/64"
1111
1112 addr:sub("ffff::", true)     -- false (underflow)
1113 print(addr)                  -- "::/64"</pre>
1114
1115
1116
1117 <h3>Return value:</h3>
1118 <ul>
1119         <li>When substracting inplace: Return <code>true</code> if the substraction
1120             succeded or <code>false</code> when the substraction underflowed.</li>
1121         <li>When deriving new CIDR: Return new instance representing the value of
1122         this instance minus the substracted amount or the lowest address if
1123             the substraction underflowed.</li></ul>
1124
1125
1126
1127 </dd>
1128
1129
1130
1131
1132 <dt><a name="cidr.minhost"></a><strong>cidr:minhost</strong>&nbsp;()</dt>
1133 <dd>
1134
1135
1136 Calculate the lowest possible host address within this CIDR instance.
1137
1138
1139
1140
1141
1142
1143 <h3>Usage:</h3>
1144 <pre>local addr = luci.ip.new("192.168.123.56/24")
1145 print(addr:minhost())  -- "192.168.123.1"
1146
1147 local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
1148 print(addr6:minhost()) -- "fd9b:62b3:9cc5::1"</pre>
1149
1150
1151
1152 <h3>Return value:</h3>
1153 Returns a new CIDR instance representing the lowest host address
1154         within this range.
1155
1156
1157
1158 </dd>
1159
1160
1161
1162
1163 <dt><a name="cidr.maxhost"></a><strong>cidr:maxhost</strong>&nbsp;()</dt>
1164 <dd>
1165
1166
1167 Calculate the highest possible host address within this CIDR instance.
1168
1169
1170
1171
1172
1173
1174 <h3>Usage:</h3>
1175 <pre>local addr = luci.ip.new("192.168.123.56/24")
1176 print(addr:maxhost())  -- "192.168.123.254" (.255 is broadcast)
1177
1178 local addr6 = luci.ip.new("fd9b:62b3:9cc5:0:221:63ff:fe75:aa17/64")
1179 print(addr6:maxhost()) -- "fd9b:62b3:9cc5:0:ffff:ffff:ffff:ffff"</pre>
1180
1181
1182
1183 <h3>Return value:</h3>
1184 Returns a new CIDR instance representing the highest host address
1185         within this range.
1186
1187
1188
1189 </dd>
1190
1191
1192
1193
1194 <dt><a name="cidr.string"></a><strong>cidr:string</strong>&nbsp;()</dt>
1195 <dd>
1196
1197
1198 Convert CIDR instance into string representation.
1199
1200 If the prefix size of instance is less than 32 for IPv4 or 128 for IPv6, the
1201 address is returned in the form "address/prefix" otherwise just "address".
1202
1203 It is usually not required to call this function directly as CIDR objects
1204 define it as __tostring function in the associated metatable.
1205
1206
1207
1208
1209
1210
1211
1212
1213 <h3>Return value:</h3>
1214 Returns a string representing the range or address of this CIDR instance
1215
1216
1217
1218 </dd>
1219
1220
1221 </dl>
1222
1223
1224
1225
1226
1227 </div> <!-- id="content" -->
1228
1229 </div> <!-- id="main" -->
1230
1231 <div id="about">
1232         <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>
1233 </div> <!-- id="about" -->
1234
1235 </div> <!-- id="container" -->
1236 </body>
1237 </html>