Class IP

The IP class. Unlike the static IPUtil class, this class provides several instance methods that can be used to perform validations on the same IP or CIDR address multiple times.

To initialize a new instance, use IP.newFromText (or IP.newFromRange):

const ip = IP.newFromText('fd12:3456:789a:1::1');
if (!ip) {
	return;
}
console.log(ip.stringify()); // fd12:3456:789a:1:0:0:0:1

Hierarchy

  • IPBase
    • IP

Constructors

constructor

Accessors

version

Methods

contains containsAll containsAny equals equalsAll equalsAny getBitLength getProperties getRange getVersion isCIDR isIPv4 isIPv4CIDR isIPv6 isIPv6CIDR isInAllRanges isInAnyRange isInRange stringify toString checkEquality clean compareRanges getRangeObject modCase newFromRange newFromText parse parseAndStringify parseRange stringify

Constructors

Privateconstructor

  • new IP(range): IP
  • Private

    Private constructor. Use IP.newFromText instead.

    Parameters

    • range: RangeObject

      An object that stores CIDR information.

    Returns IP

Accessors

version

  • get version(): 4 | 6

  • Return the IP version as a number.

    Returns 4 | 6

Methods

contains

  • contains(ipStr): null | boolean

  • Evaluate whether the IP address associated with this instance contains that associated with ipStr.

    Parameters

    • ipStr: string | IP

    Returns null | boolean

    null if ipStr does not represent an IP address.

containsAll

  • containsAll(ipArr): null | boolean

  • Evaluate whether the IP address associated with this instance contains all IP addresses in the ipArr array.

    Parameters

    • ipArr: (string | IP)[]

      An array of IP- or CIDR-representing strings or IP instances.

    Returns null | boolean

    null if ipArr is not an array or an empty array.

containsAny

  • containsAny(ipArr): number

  • Evaluate whether the IP address associated with this instance contains any IP address in the ipArr array.

    Parameters

    • ipArr: (string | IP)[]

      An array of IP- or CIDR-representing strings or IP instances.

    Returns number

    The index number of the first match in the ipArr array, or -1 otherwise.

equals

  • equals(ipStr): null | boolean

  • Evaluate whether the IP address associated with this intance equals that associated with ipStr.

    Parameters

    • ipStr: string | IP

      An IP- or CIDR-representing string, or an IP instance.

    Returns null | boolean

    null if ipStr does not represent an IP address.

equalsAll

  • equalsAll(ipArr): null | boolean

  • Evaluate whether the IP address associated with this intance equals all IP addresses in the ipArr array.

    Parameters

    • ipArr: (string | IP)[]

      An array of IP- or CIDR-representing strings or IP instances.

    Returns null | boolean

    null if ipArr is not an array or an empty array.

equalsAny

  • equalsAny(ipArr): number

  • Evaluate whether the IP address associated with this intance equals any IP address in the ipArr array.

    Parameters

    • ipArr: (string | IP)[]

      An array of IP- or CIDR-representing strings or IP instances.

    Returns number

    The index number of the first match in the ranges array, or -1 otherwise.

getBitLength

  • getBitLength(): number

  • Get the bit length of the IP instance.

    Note that this always returns a number between 0-32 for IPv4 and 0-128 for IPv6. To evaluate whether the instance is a CIDR, use IP.isCIDR.

    Returns number

getProperties

getRange

  • getRange(getObject?, options?): {
        bitLen: number;
        cidr: string;
        first: string;
        last: string;
    }

  • Get range information of the IP instance. The return value includes:

    • The (forced) CIDR notation of the IP address associated with the instance.
    • The bit length of the CIDR as a number.
    • The starting IP address of the CIDR as a string.
    • The ending IP address of the CIDR as a string.

    Parameters

    Returns {
        bitLen: number;
        cidr: string;
        first: string;
        last: string;
    }

    • bitLen: number
    • cidr: string
    • first: string
    • last: string
  • getRange(getObject, options?): {
        bitLen: number;
        cidr: string;
        first: IP;
        last: IP;
    }

  • Get range information of the IP instance. The return value includes:

    • The (forced) CIDR notation of the IP address associated with the instance.
    • The bit length of the CIDR as a number.
    • The starting IP address of the CIDR as an IP object.
    • The ending IP address of the CIDR as an IP object.

    Parameters

    Returns {
        bitLen: number;
        cidr: string;
        first: IP;
        last: IP;
    }

    • bitLen: number
    • cidr: string
    • first: IP
    • last: IP

getVersion

  • getVersion(): string

  • Get the IP version as a string in the format of IPvN.

    Returns string

isCIDR

  • isCIDR(): boolean

  • Evaluate whether the IP address associated with the instance is a CIDR address.

    Returns boolean

isIPv4

  • isIPv4(allowCidr?): boolean

  • Evaluate whether the IP address associated with the instance is an IPv4 address.

    Parameters

    • OptionalallowCidr: boolean = false

      Whether to allow a CIDR address, which defaults to false.

    Returns boolean

isIPv4CIDR

  • isIPv4CIDR(): boolean

  • Evaluate whether the IP address associated with the instance is an IPv4 CIDR address.

    Returns boolean

isIPv6

  • isIPv6(allowCidr?): boolean

  • Evaluate whether the IP address associated with the instance is an IPv6 address.

    Parameters

    • OptionalallowCidr: boolean = false

      Whether to allow a CIDR address, which defaults to false.

    Returns boolean

isIPv6CIDR

  • isIPv6CIDR(): boolean

  • Evaluate whether the IP address associated with the instance is an IPv6 CIDR address.

    Returns boolean

isInAllRanges

  • isInAllRanges(cidrArr): null | boolean

  • Evaluate whether the IP address associated with this instance is within all IP ranges in the cidrArr array.

    Parameters

    • cidrArr: (string | IP)[]

      An array of IP- or CIDR-representing strings or IP instances.

    Returns null | boolean

    null if cidrArr is not an array or an empty array.

isInAnyRange

  • isInAnyRange(cidrArr): number

  • Evaluate whether the IP address associated with this instance is within any IP range in the cidrArr array.

    Parameters

    • cidrArr: (string | IP)[]

      An array of IP- or CIDR-representing strings or IP instances.

    Returns number

    The index number of the first match in the cidrArr array, or -1 otherwise.

isInRange

  • isInRange(cidrStr): null | boolean

  • Evaluate whether the IP address associated with this instance is within that associated with cidrStr.

    Parameters

    • cidrStr: string | IP

    Returns null | boolean

    null if cidrStr does not represent an IP address.

stringify

  • stringify(options?): string

  • Stringify the IP instance.

    Parameters

    • Optionaloptions: StringifyOptions = {}

      Options to specify the format of the output. If not provided, the "sanitized" format will be used.

    Returns string

    Note that even if the instance was initialized from an inaccurate CIDR string, the output will be in a "corrected" format:

    const ip = IP.newFromText('fd12:3456:789a:1::1/64');
    ip.stringify(); // fd12:3456:789a:1:0:0:0:0/64

toString

  • toString(): string

  • Same as IP.stringify when it's called without options.

    Returns string

Protected StaticcheckEquality

  • checkEquality(ipObj, ipStr): null | boolean
  • Protected

    Check the equality of two IP addresses.

    Parameters

    • ipObj: RangeObject

      An object of arrays of the IP parts in decimals.

    • ipStr: string | IP

      An IP- or CIDR-representing string, or an IP instance.

    Returns null | boolean

    null if ipStr does not represent an IP address.

Staticclean

  • clean(str): string

  • Return a trimmed string from which all occurrences of unicode bidi characters are removed.

    "Unicode bidi characters" are special characters shown as red dots in WikiEditor, which can slip into cut-and-pasted strings. When we evaluate whether a string represents an IP address, these can cause serious trouble.

    Parameters

    • str: string

    Returns string

    See

    MediaWikiTitleCodec::splitTitleString in MediaWiki core

Protected StaticcompareRanges

  • compareRanges(ip1, ip2, comparator): null | boolean
  • Protected

    Compare two ranges to check their inclusion relationship.

    Parameters

    • ip1: RangeObject

      An object of arrays of the IP parts in decimals.

    • ip2: string | IP
    • comparator: "<" | ">"

      Which of ip1 and ip2 is expected to be broader.

    Returns null | boolean

    null if ip2 does not represent an IP address.

Protected StaticgetRangeObject

  • getRangeObject(ip): null | RangeObject
  • Protected

    Given an IP string or instance, parse it into an object of arrays of decimals that represent the parts of the first and last IPs.

    Parameters

    • ip: string | IP

    Returns null | RangeObject

    null if the input string does not represent an IP address.

Protected StaticmodCase

  • modCase(str, upper?): string
  • Protected

    Change the casing of a string.

    Parameters

    • str: string
    • Optionalupper: boolean = false

      Whether to capitalize the output, which defaults to false.

    Returns string

    The original string if upper isn't true.

StaticnewFromRange

  • newFromRange(ipStr, range): null | IP

  • Initialize an IP instance from a string and a range (aka bit length).

    Parameters

    • ipStr: string

      An IP- or CIDR-representing string. If a CIDR string is passed, the /XX part will be overriden by range.

    • range: number

      0-32 for IPv4, 0-128 for IPv6.

    Returns null | IP

    null if:

    • The input string does not represent an IP address.
    • The bit length specified by range is invalid.

    Throws

    If range is not a number.

StaticnewFromText

  • newFromText(ipStr): null | IP

  • Initialize an IP instance from a string.

    Parameters

    • ipStr: string

      An IP- or CIDR-representing string.

    Returns null | IP

    null if the input string does not represent an IP address.

Protected Staticparse

  • parse(ipStr, bitLen?): null | Parsed
  • Protected

    Parse a string that potentially represents an IP or CIDR address.

    Parameters

    • ipStr: string
    • OptionalbitLen: number

      An optional bit length of the IP address.

    Returns null | Parsed

    A parsed object, or null if:

    • ipStr is not a string.
    • ipStr does not represent an IP address.
    • ipStr contains an invalid bit length for a CIDR.

Protected StaticparseAndStringify

  • parseAndStringify(ipStr, options, conditionPredicate?): null | string
  • Protected

    Parse an IP string into an array and convert back into a string.

    Parameters

    Returns null | string

    null if:

    • The input string does not represent an IP address.
    • The parsed IP address does not meet the conditions specified by conditionPredicate

Protected StaticparseRange

  • parseRange(parts, bitLen): RangeObject
  • Protected

    Get the start and end IP addresses for the range of bitLen as an object of arrays of decimals.

    Parameters

    • parts: number[]
    • bitLen: null | number

    Returns RangeObject

Protected Staticstringify

  • stringify(decimals, suffix, options?): string
  • Protected

    Stringify an array of IP parts in decimals.

    Parameters

    Returns string

Settings

Member Visibility

On This Page

Constructors
Accessors
Methods