diff --git a/README.md b/README.md index 78d6ede..2adc65f 100644 --- a/README.md +++ b/README.md @@ -3,26 +3,31 @@ VBA functions for IP manipulation and IP/Subnet lookup ## Functions List +Unless otherwise specified, IP address arguments are given as strings in standard IPv4 d.d.d.d decimal notation, and subnet arguments +are given in either CIDR notation, or a base address and mask pair, separated by a space. + +### IpIsValid(_ip_) -###IpIsValid Returns true if an ip address is formated exactly as it should be: no space, no extra zero, no incorrect value -###IpStrToBin -Converts a text IP address to binary +### IpStrToBin(_ip_) + +Converts a text IP address to binary. ex: IpStrToBin("1.2.3.4") returns 16909060 -###IpBinToStr -Converts a binary IP address to text +### IpBinToStr(_ipnum_) + +Converts a binary IP address to text. ex: IpBinToStr(16909060) returns "1.2.3.4" -###IpAdd +### IpAdd(_ip_; _offset_) ex: @@ -30,7 +35,8 @@ ex: IpAdd("192.168.1.1"; 256) returns "192.168.2.1" -###IpAnd +### IpAnd(_ip-1_; _ip-2_) + IP logical AND ex: @@ -38,26 +44,30 @@ ex: IpAnd("192.168.1.1"; "255.255.255.0") returns "192.168.1.0" -###IpAdd2 -another implementation of IpAdd which not use the binary representation +### IpAdd2(_ip_; _offset_) + +Another implementation of IpAdd which does not use the binary representation internally. -###IpGetByte -get one byte from an ip address given its position +### IpGetByte(_ip_; _position_) + +Get one byte from an ip address given its position, counted from the most significant byte starting as one. ex: IpGetByte("192.168.1.1"; 1) returns 192 -###IpSetByte -set one byte in an ip address given its position and value +### IpSetByte(_ip_; _position_; _value_) + +Set one byte in an ip address given its position, counted from the most significant byte as one, and new value. ex: IpSetByte("192.168.1.1"; 4; 20) returns "192.168.1.20" -###IpMask -returns an IP netmask from a subnet -both notations are accepted +### IpMask(_subnet_) + +Returns an IP netmask from a subnet. +Accepts either CIDR notation or address-and-mask. ex: @@ -65,9 +75,10 @@ ex: IpMask("192.168.1.1 255.255.255.0") returns "255.255.255.0" -###IpWildMask -returns an IP Wildcard (inverse) mask from a subnet -both notations are accepted +### IpWildMask(_subnet_) + +Returns an IP Wildcard (inverse) mask from a subnet. +Accepts either CIDR notation or address-and-mask. ex: @@ -75,9 +86,9 @@ ex: IpWildMask("192.168.1.1 255.255.255.0") returns "0.0.0.255" -###IpInvertMask -returns an IP Wildcard (inverse) mask from a subnet mask -or a subnet mask from a wildcard mask +### IpInvertMask(_ip_) + +Inverts all bits of an IP address. Typically used to generate a wild card mask from a subnet mask, or vice versa. ex: @@ -85,15 +96,17 @@ ex: IpWildMask("0.0.0.255") returns "255.255.255.0" -###IpMaskLen -returns prefix length from a mask given by a string notation (xx.xx.xx.xx) +### IpMaskLen(_mask_) + +Returns prefix length from a mask given by a string notation (xx.xx.xx.xx). ex: IpMaskLen("255.255.255.0") returns 24 which is the number of bits of the subnetwork prefix -###IpWithoutMask -removes the netmask notation at the end of the IP +### IpWithoutMask(_subnet_) + +Removes the mask notation from a subnet string, returning the base ip. ex: @@ -101,16 +114,18 @@ ex: IpWithoutMask("192.168.1.1 255.255.255.0") returns "192.168.1.1" -###IpSubnetLen -get the mask len from a subnet +### IpSubnetLen(_subnet_) + +Returns the mask len from a subnet string. ex: IpSubnetLen("192.168.1.1/24") returns 24 IpSubnetLen("192.168.1.1 255.255.255.0") returns 24 -###IpSubnetSize -returns the number of addresses in a subnet +### IpSubnetSize(_subnet_) + +Returns the number of addresses in a subnet. ex: @@ -118,8 +133,9 @@ ex: IpSubnetSize("192.168.1.0 255.255.255.0") returns 256 -###IpClearHostBits -set to zero the bits in the host part of an address +### IpClearHostBits(_subnet_) + +Returns a subnet string with with the host bits of the base address set to zero. ex: @@ -127,9 +143,9 @@ ex: IpClearHostBits("192.168.1.193 255.255.255.128") returns "192.168.1.128 255.255.255.128" -###IpIsInSubnet -returns TRUE if "ip" is in "subnet" -subnet must have the / mask notation (xx.xx.xx.xx/yy) +### IpIsInSubnet(_ip_; _subnet_) + +Returns TRUE if the given IP is in the given subnet. ex: @@ -140,28 +156,29 @@ ex: IpIsInSubnet("192.168.1.41"; "192.168.1.32/29") returns FALSE -###IpSubnetVLookup -tries to match an IP address against a list of subnets in the left-most -column of table_array and returns the value in the same row based on the -index_number +### IpSubnetVLookup(_ip_; _range_; _index_) + +Tries to match an IP address against a list of subnets in the left-most +column of _range_ and returns the value in the same row based on _index_. this function selects the smallest matching subnet "ip" is the value to search for in the subnets in the first column of the table_array -"table_array" is one or more columns of data +"range" is one or more columns of data -"index_number" is the column number in table_array from which the matching +"index" is the column number in table_array from which the matching value must be returned. The first column which contains subnets is 1. -note: add the subnet 0.0.0.0/0 at the end of the array if you want the -function to return a default value +note: Add the subnet 0.0.0.0/0 at the end of the array if you want the +function to return a default value. -###IpSubnetMatch -tries to match an IP address against a list of subnets in the left-most -column of table_array and returns the row number -this function selects the smallest matching subnet +### IpSubnetMatch(_ip_; _range_) + +Tries to match an IP address against a list of subnets in the left-most +column of _range_ and returns the row number. +This function selects the smallest matching subnet. "ip" is the value to search for in the subnets in the first column of the table_array @@ -170,9 +187,10 @@ this function selects the smallest matching subnet returns 0 if the IP address is not matched. -###IpSubnetIsInSubnet -returns TRUE if "subnet1" is in "subnet2" -subnets must have the / mask notation (xx.xx.xx.xx/yy) +### IpSubnetIsInSubnet(_subnet-1_; _subnet-2_) + +Returns TRUE if "subnet1" is in "subnet2". +Subnets must have the / mask notation (xx.xx.xx.xx/yy) ex: @@ -183,12 +201,12 @@ ex: IpSubnetIsInSubnet("192.168.1.35/28"; "192.168.1.32/29") returns FALSE -###IpSubnetInSubnetVLookup -tries to match a subnet against a list of subnets in the left-most -column of table_array and returns the value in the same row based on the -index_number -the value matches if 'subnet' is equal or included in one of the subnets -in the array +### IpSubnetInSubnetVLookup(_subnet_; _range_; _index_) + +Tries to match a subnet against a list of subnets in the left-most +column of _range_ and returns the value in the same row based on _index_. +The value matches if _subnet_ is equal to or included in one of the subnets +in the array. "subnet" is the value to search for in the subnets in the first column of the table_array @@ -198,14 +216,15 @@ in the array "index_number" is the column number in table_array from which the matching value must be returned. The first column which contains subnets is 1. -note: add the subnet 0.0.0.0/0 at the end of the array if you want the -function to return a default value +note: Add the subnet 0.0.0.0/0 at the end of the array if you want the +function to return a default value. + +### IpSubnetInSubnetMatch(_subnet_; _range_) -###IpSubnetInSubnetMatch -tries to match a subnet against a list of subnets in the left-most +Tries to match a subnet against a list of subnets in the left-most column of table_array and returns the row number -the value matches if 'subnet' is equal or included in one of the subnets -in the array +the value matches if _subnet_ is equal to or included in one of the subnets +in the array. "subnet" is the value to search for in the subnets in the first column of the table_array @@ -214,74 +233,80 @@ in the array returns 0 if the subnet is not included in any of the subnets from the list -###IpFindOverlappingSubnets -this function must be used in an array formula -it will find in the list of subnets which subnets overlap +### IpFindOverlappingSubnets(_subnets_) -"SubnetsArray" is single column array containing a list of subnets, the -list may be sorted or not -the return value is also a array of the same size -if the subnet on line x is included in a larger subnet from another line, +This function must be used in an array formula. +It will find which subnets overlap in the given list of subnets. + +_subnets_ is single column array containing a list of subnets, the +list may be sorted or not. +The return value is also an array of the same size. +If the subnet on line x is included in a larger subnet from another line, this function returns an array in which line x contains the value of the -larger subnet -if the subnet on line x is distinct from any other subnet in the array, -then this function returns on line x an empty cell -if there are no overlapping subnets in the input array, the returned array -is empty +larger subnet. +If the subnet on line x is distinct from any other subnet in the array, +then this function returns an empty cell on line x. +If there are no overlapping subnets in the input array, the returned array +is empty. + +### IpSortArray(_ips_[; _descending_]) -###IpSortArray -this function must be used in an array formula +This function must be used in an array formula. -"ip_array" is a single column array containing ip addresses -the return value is also a array of the same size containing the same -addresses sorted in ascending or descending order +_ips_ is a single column array containing ip addresses. +The return value is also a array of the same size containing the same +addresses sorted in ascending or descending order. -"descending" is an optional parameter, if set to True the addresses are +_descending_ is an optional parameter, if set to True the addresses are sorted in descending order -###IpSubnetSortArray -this function must be used in an array formula +### IpSubnetSortArray(_ips_[; _descending_]) -"ip_array" is a single column array containing ip subnets in "prefix/len" -or "prefix mask" notation -the return value is also an array of the same size containing the same -subnets sorted in ascending or descending order +This function must be used in an array formula. -"descending" is an optional parameter, if set to True the subnets are -sorted in descending order +_ips_ is a single column array containing ip subnets in "prefix/len" +or "prefix mask" notation. +The return value is also an array of the same size containing the same +subnets sorted in ascending or descending order. + +_descending_ is an optional parameter, if set to True the subnets are +sorted in descending order. -###IpParseRoute -this function is used by IpSubnetSortJoinArray to extract the subnet -and next hop in route -the supported formats are +### IpParseRoute - _internal utility subroutine_ -10.0.0.0 255.255.255.0 1.2.3.4 +This function is used by IpSubnetSortJoinArray to extract the subnet +and next hop in route. -10.0.0.0/24 1.2.3.4 +The supported formats are: + + 10.0.0.0 255.255.255.0 1.2.3.4 + + 10.0.0.0/24 1.2.3.4 the next hop can be any character sequence, and not only an IP -###IpSubnetSortJoinArray -this fuction car sort and summarize subnets or ip routes -it must be used in an array formula +### IpSubnetSortJoinArray(_ips_) + +This fuction can sort and summarize subnets or ip routes. +It must be used in an array formula. -"ip_array" is a single column array containing ip subnets in "prefix/len" +_ips_ is a single column array containing ip subnets in "prefix/len" or "prefix mask" notation -the return value is also an array of the same size containing the same -subnets sorted in ascending order -any consecutive subnets of the same size will be summarized when it is -possible -each line may contain any character sequence after the subnet, such as -a next hop or any parameter of an ip route -in this case, only subnets with the same parameters will be summarized +The return value is also an array of the same size containing the same +subnets sorted in ascending order. +Any consecutive subnets of the same size will be summarized when possible. +Each line may contain any character sequence after the subnet, such as +a next hop or any parameter of an ip route. +In this case, only subnets with the same parameters will be summarized. -###IpDivideSubnet -divide a network in smaller subnets +### IpDivideSubnet(_subnet_; _n_; _index_) -"n" is the value that will be added to the subnet length +Divide a network in smaller subnets. -"SubnetSeqNbr" is the index of the smaller subnet to return +_n_ is the value that will be added to the subnet length + +_index_ is the index of the smaller subnet to return ex: @@ -290,8 +315,9 @@ ex: IpDivideSubnet("1.2.3.0/24"; 2; 1) returns "1.2.3.64/26" -###IpIsPrivate -returns TRUE if "ip" is in one of the private IP address ranges +### IpIsPrivate(_ip_) + +Returns TRUE if _ip_ is in one of the private IP address ranges. ex: @@ -300,17 +326,19 @@ ex: IpIsPrivate("209.85.148.104") returns FALSE -###IpDiff -difference between 2 IP addresses +### IpDiff(_ip-1_; _ip-2_) + +Difference between 2 IP addresses. ex: IpDiff("192.168.1.7"; "192.168.1.1") returns 6 -###IpParse -Parses an IP address by iteration from right to left -Removes one byte from the right of "ip" and returns it as an integer +### IpParse(_ip-by-ref_) + +Parses an IP address by iteration from right to left. +Removes one byte from the right of _ip-by-ref_ and returns it as an integer. ex: @@ -318,9 +346,10 @@ ex: IpParse(ip) returns 32 and ip="192.168.1" when the function returns -###IpBuild -Builds an IP address by iteration from right to left -Adds "ip_byte" to the left the "ip" +### IpBuild(_byte_; _ip-by-ref_) + +Builds an IP address by iteration from right to left. +Adds _byte_ to the left of _ip_. If "ip_byte" is greater than 255, only the lower 8 bits are added to "ip" and the remaining bits are returned to be used on the next IpBuild call @@ -338,8 +367,9 @@ ex 2: IpBuild(258, ip) returns 1 and ip="2.1" -###IpMaskBin -returns binary IP mask from an address with / notation (xx.xx.xx.xx/yy) +### IpMaskBin(_subnet_) + +Returns binary IP mask from an address with / notation (xx.xx.xx.xx/yy). ex: