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