https://h3geo.org/assets/js/68225966.7db9553b.js

1"use strict";(globalThis.webpackChunkh3_website||=[]).push([[1195],{8470(e,r,n){n.r(r),n.d(r,{assets:()=>c,contentTitle:()=>l,default:()=>h,frontMatter:()=>d,metadata:()=>s,toc:()=>o});const s=JSON.parse('{"id":"library/errors","title":"Error handling","description":"H3 does it\'s best to be robust to system failures or unexpected inputs, but","source":"@site/docs/library/errors.md","sourceDirName":"library","slug":"/library/errors","permalink":"/docs/library/errors","draft":false,"unlisted":false,"editUrl":"https://github.com/uber/h3/edit/master/website/docs/library/errors.md","tags":[],"version":"current","frontMatter":{"id":"errors","title":"Error handling","sidebar_label":"Error handling","slug":"/library/errors"},"sidebar":"someSidebar","previous":{"title":"Terminology","permalink":"/docs/library/terminology"},"next":{"title":"Tables of cell stats","permalink":"/docs/core-library/restable"}}');var t=n(4848),i=n(8453);const d={id:"errors",title:"Error handling",sidebar_label:"Error handling",slug:"/library/errors"},l=void 0,c={},o=[{value:"Example",id:"example",level:2},{value:"H3Error type",id:"h3error-type",level:2},{value:"Table of error codes",id:"table-of-error-codes",level:2},{value:"Bindings",id:"bindings",level:3},{value:"References",id:"references",level:2}];function a(e){const r={a:"a",code:"code",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,i.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(r.p,{children:"H3 does it's best to be robust to system failures or unexpected inputs, but\nsome times these cannot be recovered from. H3's way of doing this is to return\nan error code to the caller."}),"\n",(0,t.jsx)(r.h2,{id:"example",children:"Example"}),"\n",(0,t.jsx)(r.p,{children:"This code example checks for an error when calling an H3 function and prints a message if the call did not succeed:"}),"\n",(0,t.jsx)(r.pre,{children:(0,t.jsx)(r.code,{className:"language-c",children:'H3Error err;\nH3Index result;\n\nerr = latLngToCell(lat, lng, res, &result);\nif (err) {\n    fprintf(stderr, "Error: %d", err);\n}\n'})}),"\n",(0,t.jsx)(r.h2,{id:"h3error-type",children:"H3Error type"}),"\n",(0,t.jsxs)(r.p,{children:["The type returned by most H3 functions is ",(0,t.jsx)(r.code,{children:"H3Error"}),", a 32 bit integer type with the following properties:"]}),"\n",(0,t.jsxs)(r.ul,{children:["\n",(0,t.jsxs)(r.li,{children:[(0,t.jsx)(r.code,{children:"H3Error"})," will be an integer type of 32 bits, i.e. ",(0,t.jsx)(r.code,{children:"uint32_t"}),"."]}),"\n",(0,t.jsxs)(r.li,{children:[(0,t.jsx)(r.code,{children:"H3Error"})," with value 0 indicates success (no error)."]}),"\n",(0,t.jsxs)(r.li,{children:["No ",(0,t.jsx)(r.code,{children:"H3Error"})," value will set the most significant bit."]}),"\n",(0,t.jsxs)(r.li,{children:["As a result of these properties, no ",(0,t.jsx)(r.code,{children:"H3Error"})," value will set the bits that correspond with the ",(0,t.jsx)(r.strong,{children:"Mode"})," bit field in an ",(0,t.jsx)(r.code,{children:"H3Index"}),"."]}),"\n"]}),"\n",(0,t.jsx)(r.p,{children:"32 bit return codes with the high bit never set allows for mixing error codes and resulting indexes if desired by the application, after copying the error codes into the result buffer."}),"\n",(0,t.jsx)(r.h2,{id:"table-of-error-codes",children:"Table of error codes"}),"\n",(0,t.jsxs)(r.table,{children:[(0,t.jsx)(r.thead,{children:(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.th,{children:"Value"}),(0,t.jsx)(r.th,{children:"Name"}),(0,t.jsx)(r.th,{children:"Description"})]})}),(0,t.jsxs)(r.tbody,{children:[(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"0"}),(0,t.jsx)(r.td,{children:"E_SUCCESS"}),(0,t.jsx)(r.td,{children:"Success (no error)"})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"1"}),(0,t.jsx)(r.td,{children:"E_FAILED"}),(0,t.jsx)(r.td,{children:"The operation failed but a more specific error is not available"})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"2"}),(0,t.jsx)(r.td,{children:"E_DOMAIN"}),(0,t.jsx)(r.td,{children:"Argument was outside of acceptable range (when a more specific error code is not available)"})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"3"}),(0,t.jsx)(r.td,{children:"E_LATLNG_DOMAIN"}),(0,t.jsx)(r.td,{children:"Latitude or longitude arguments were outside of acceptable range"})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"4"}),(0,t.jsx)(r.td,{children:"E_RES_DOMAIN"}),(0,t.jsx)(r.td,{children:"Resolution argument was outside of acceptable range"})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"5"}),(0,t.jsx)(r.td,{children:"E_CELL_INVALID"}),(0,t.jsxs)(r.td,{children:[(0,t.jsx)(r.code,{children:"H3Index"}

1)," cell argument was not valid"]})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"6"}),(0,t.jsx)(r.td,{children:"E_DIR_EDGE_INVALID"}),(0,t.jsxs)(r.td,{children:[(0,t.jsx)(r.code,{children:"H3Index"})," directed edge argument was not valid"]})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"7"}),(0,t.jsx)(r.td,{children:"E_UNDIR_EDGE_INVALID"}),(0,t.jsxs)(r.td,{children:[(0,t.jsx)(r.code,{children:"H3Index"})," undirected edge argument was not valid"]})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"8"}),(0,t.jsx)(r.td,{children:"E_VERTEX_INVALID"}),(0,t.jsxs)(r.td,{children:[(0,t.jsx)(r.code,{children:"H3Index"})," vertex argument was not valid"]})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"9"}),(0,t.jsx)(r.td,{children:"E_PENTAGON"}),(0,t.jsx)(r.td,{children:"Pentagon distortion was encountered which the algorithm could not handle it"})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"10"}),(0,t.jsx)(r.td,{children:"E_DUPLICATE_INPUT"}),(0,t.jsx)(r.td,{children:"Duplicate input was encountered in the arguments and the algorithm could not handle it"})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"11"}),(0,t.jsx)(r.td,{children:"E_NOT_NEIGHBORS"}),(0,t.jsxs)(r.td,{children:[(0,t.jsx)(r.code,{children:"H3Index"})," cell arguments were not neighbors"]})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"12"}),(0,t.jsx)(r.td,{children:"E_RES_MISMATCH"}),(0,t.jsxs)(r.td,{children:[(0,t.jsx)(r.code,{children:"H3Index"})," cell arguments had incompatible resolutions"]})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"13"}),(0,t.jsx)(r.td,{children:"E_MEMORY_ALLOC"}),(0,t.jsx)(r.td,{children:"Necessary memory allocation failed"})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"14"}),(0,t.jsx)(r.td,{children:"E_MEMORY_BOUNDS"}),(0,t.jsx)(r.td,{children:"Bounds of provided memory were not large enough"})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"15"}),(0,t.jsx)(r.td,{children:"E_OPTION_INVALID"}),(0,t.jsx)(r.td,{children:"Mode or flags argument was not valid"})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"16"}),(0,t.jsx)(r.td,{children:"E_INDEX_INVALID"}),(0,t.jsxs)(r.td,{children:[(0,t.jsx)(r.code,{children:"H3Index"})," argument was not valid"]})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"17"}),(0,t.jsx)(r.td,{children:"E_BASE_CELL_DOMAIN"}),(0,t.jsx)(r.td,{children:"Base cell number was outside of acceptable range"})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"18"}),(0,t.jsx)(r.td,{children:"E_DIGIT_DOMAIN"}),(0,t.jsx)(r.td,{children:"Child indexing digits invalid"})]}),(0,t.jsxs)(r.tr,{children:[(0,t.jsx)(r.td,{children:"19"}),(0,t.jsx)(r.td,{children:"E_DELETED_DIGIT"}),(0,t.jsx)(r.td,{children:"Child indexing digits refer to a deleted subsequence"})]})]})]}),"\n",(0,t.jsxs)(r.p,{children:["The H3 library may always add additional error messages. Error messages not recognized by the application should be treated as ",(0,t.jsx)(r.code,{children:"E_FAILED"}),"."]}),"\n",(0,t.jsxs)(r.p,{children:["The C library has a value ",(0,t.jsx)(r.code,{children:"H3_ERROR_END"})," which is one past the last defined error message. This is for convenience when iterating over error messages."]}),"\n",(0,t.jsx)(r.h3,{id:"bindings",children:"Bindings"}),"\n",(0,t.jsx)(r.p,{children:"Bindings translate error codes into the error handling mechanism appropriate to their language. For example, Java will convert error codes into Java Exceptions."}),"\n",(0,t.jsx)(r.p,{children:"When possible, it is preferable to retain the error code. When this is not possible it is fine to elide them. Language bindings should include error messages that are formatted as is usual in their language."}),"\n",(0,t.jsx)(r.h2,{id:"references",children:"References"}),"\n",(0,t.jsxs)(r.ul,{children:["\n",(0,t.jsx)(r.li,{children:(0,t.jsx)(r.a,{href:"https://github.com/uber/h3/blob/master/dev-docs/RFCs/v4.0.0/error-handling-rfc.md",children:"Technical RFC on error handling"})}),"\n"]})]})}function h(e={}){const{wrapper:r}={...(0,i.R)(),...e.components};return r?(0,t.jsx)(r,{...e,children:(0,t.jsx)(a,{...e})}):a(e)}},8453(e,r,n){n.d(r,{R:()=>d,x:()=>l});var s=n(6540);const t={},i=s.createContext(t);function d(e){const r=s.useContext(i);return s.useMemo(function(){return"function"==typeof e?e(r):{...r,...e}},[r,e])}function l(e){let r;return r=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:d(e.components),s.createElement(i.Provider,{value:r},e.children)}}}]);