doc/api/querystring.markdown

   1 # Query String
   2
   3     Stability: 2 - Stable
   4
   5 <!--name=querystring-->
   6
   7 This module provides utilities for dealing with query strings.
   8 It provides the following methods:
   9
  10 ## querystring.stringify(obj[, sep][, eq][, options])
  11
  12 Serialize an object to a query string.
  13 Optionally override the default separator (`'&'`) and assignment (`'='`)
  14 characters.
  15
  16 Options object may contain `encodeURIComponent` property (`querystring.escape` by default),
  17 it can be used to encode string with `non-utf8` encoding if necessary.
  18
  19 Example:
  20
  21     querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' })
  22     // returns
  23     'foo=bar&baz=qux&baz=quux&corge='
  24
  25     querystring.stringify({foo: 'bar', baz: 'qux'}, ';', ':')
  26     // returns
  27     'foo:bar;baz:qux'
  28
  29     // Suppose gbkEncodeURIComponent function already exists,
  30     // it can encode string with `gbk` encoding
  31     querystring.stringify({ w: '中文', foo: 'bar' }, null, null,
  32       { encodeURIComponent: gbkEncodeURIComponent })
  33     // returns
  34     'w=%D6%D0%CE%C4&foo=bar'
  35
  36 ## querystring.parse(str[, sep][, eq][, options])
  37
  38 Deserialize a query string to an object.
  39 Optionally override the default separator (`'&'`) and assignment (`'='`)
  40 characters.
  41
  42 Options object may contain `maxKeys` property (equal to 1000 by default), it'll
  43 be used to limit processed keys. Set it to 0 to remove key count limitation.
  44
  45 Options object may contain `decodeURIComponent` property (`querystring.unescape` by default),
  46 it can be used to decode a `non-utf8` encoding string if necessary.
  47
  48 Example:
  49
  50     querystring.parse('foo=bar&baz=qux&baz=quux&corge')
  51     // returns
  52     { foo: 'bar', baz: ['qux', 'quux'], corge: '' }
  53
  54     // Suppose gbkDecodeURIComponent function already exists,
  55     // it can decode `gbk` encoding string
  56     querystring.parse('w=%D6%D0%CE%C4&foo=bar', null, null,
  57       { decodeURIComponent: gbkDecodeURIComponent })
  58     // returns
  59     { w: '中文', foo: 'bar' }
  60
  61 ## querystring.escape
  62
  63 The escape function used by `querystring.stringify`,
  64 provided so that it could be overridden if necessary.
  65
  66 ## querystring.unescape
  67
  68 The unescape function used by `querystring.parse`,
  69 provided so that it could be overridden if necessary.
  70
  71 It will try to use `decodeURIComponent` in the first place,
  72 but if that fails it falls back to a safer equivalent that
  73 doesn't throw on malformed URLs.