Skip to content

NSRange ​

NSRange represents a range of text: length UTF-16 code units starting at location.

The unit is the same as JS string indices. So text.slice(location, location + length) extracts exactly that range, and text.length is the largest location. Most characters take one code unit; emoji and some CJK characters take two. A length of 0 is a position with no content; in a text field it is the cursor.

It is used by: the selectedRange of UITextField and UITextView, UITextView.scrollRangeToVisible(), the beforeinput event of UITextField and UITextView, the linkclick event of UITextView, and every method that takes a range on attributed strings.

NSRange is a struct: a value, not a reference to an object. The rules are the same as for CGRect and its group:

  • Fields are read-only. To change one, replace the whole value with a new one.
  • Plain objects are accepted when writing. Where an NSRange is expected, { location: 3, length: 0 } is equivalent to new NSRange(3, 0). What you read back is always an NSRange.
  • Every read returns a new object. input.selectedRange === input.selectedRange is false. Compare ranges by their fields.
  • As a string it is NSRange(3, 0); through JSON.stringify it is {"location":3,"length":0}.

Inheritance: NSRange. It does not inherit from NSObject.

Constructor ​

NSRange()

Creates a range from a start and a length.

Instance properties ​

PropertyDescription
location read-onlyWhere the range starts
length read-onlyHow long the range is

Examples ​

Selecting an emoji ​

js
const input = new UITextView();
input.text = 'a😀b';
console.log(input.text.length);
input.selectedRange = new NSRange(1, 2);
console.log(String(input.selectedRange));

Result: logs 4 and NSRange(1, 2). (1, 2) selects exactly the emoji (verified by testing).

Note: Placing the cursor between the two code units of an emoji (new NSRange(2, 0) in the example above) is not corrected. Inserting text there splits the emoji in two (verified by testing). Avoid such positions when computing them yourself.

Corresponding iOS API ​

ObjCJS
NSMakeRange(0, 5)new NSRange(0, 5)
range.locationrange.location
range.lengthrange.length
NSMaxRange(range)range.location + range.length
NSStringFromRange(range)String(range), which gives NSRange(0, 5)

See also ​